Featured

Recommended Reading

1. Helpinator

Productivity Tools For Technical Writers Part 1

Productivity Tools For Technical Writers Part 2

Productivity Tools For Technical Writers Part 3

Productivity Tools For Technical Writers Part 4

Refactoring Documentation

2. WordPress

WordPress for Online Documentation: How To Use Helpinator plugin and documentation themes

WordPress for Context-Sensitive Help

Troubleshooting WordPress

3. Knowledge Base

How to Create a Knowledge Base With Step-By-Step Guides

4. LiteHelp

Introducing LiteHelp

LiteHelp For Delphi

5. ASCIIDoc/ASCIIDoctor

ASCIIDoc/ASCIIDoctor: The easiest way to use it on Windows

6. Leanpub

Leanpub Tutorial

Creating self-help kiosk app with Helpinator and PhoneGap / Cordova

Disclaimer: since Helpinator is a Windows desktop app we will set up Windows 10 environment for this task.

Helpinator allows to generate so called MobileHelp output. It is based on JQuery Mobile framework and by design was intended to provide online help capabilities for mobile apps, and since it is html/css/js-output it is cross-platform by default, so you can use it with Android or iOS apps.

However the design of it makes it perfect fit for self-help kiosk apps that you can see here and there at the entrances of offices. They provide maps, lists of offices and companies and even instructions what you have to do in case of fire. One of our clients asked for a way to turn MobileHelp into an Android kiosk app for this purposes and we publish the instruction created for him.

Two most important feats of a kiosk app:

  1. Touch-friendly navigation, font sizes that can be easily read.
  2. There should be no option to quit the app or go to the Android backbone of it. This is essentially what a kiosk app is. If you allow a means to do it, the kiosk becomes unmaintanable with constant calls to reopen the app.

What we need to accomplish this task:

  1. We will use Apache Cordova project to turn MobileHelp into an Andoid app (apk).
  2. We will have to install Cordove prerequisited to run it
    1. Node.js and Node Package Manager – required to install Cordova itself
    2. Java Development Kit (JDK)
    3. Android Studio (unfortunately “standalone” Android SKDs that are available do not do the job)
    4. Gradle (actually comes with Andoid Studio, but it’s better to install it on our own).

To install Node.js go to https://nodejs.org/en/download/ and select installer for Windows version that you use.

Node.js installer

Install it into a folder outside of Program Files, say C:\nodejs

Now let’s install JDK for Windows from https://www.oracle.com/java/technologies/jdk8-downloads.html Unfortunately most likely Oracle will force you to create an account to open download links. Download the installer and install JDK into a folder like C:\JDK.

Next step is to download and install Gradle. Do it here https://gradle.org/releases/ Unzip the package to “C:\” and rename gradle-X.X.X folder to just “C:\gradle” for simplicity.

The next step is to install Andoid Studio, download the installer here: https://developer.android.com/studio Install and run the studio, create a sample project, it will download and create important SDK entries.

Now even the more boring part – you need to put paths to bin folders of all tolls to the PATH system environment variable and add a couple more variables as well.

This article tells in detail how to reach environment variables on Windows 10: https://www.architectryan.com/2018/03/17/add-to-the-path-on-windows-10/

Add the following paths to the system PATH variable: “C:\JDK\bin”, “C:\nodejs”, “C:\gradle\bin”. If we assume that you also store “Users” folder on C: drive you need to add the following, where <Username> is your Windows user name: “C:\Users\<Username>\Android\SKD\tools”, “C:\Users\<Username>\Android\SDK\tools\bin” , “C:\Users\<Username>\Android\SDK\platform-tools”.

Add new system variables:

  1. JAVA_HOME=”C:\JDK”
  2. ANDROID_SDK_ROOT=”C:\Users\<Username>\Android\SDK\ “

Now let’s install Cordova itself. Open command prompt and go to the “C:\nodejs” folder. Execute the following command:

npm install -g cordova

Now create a folder to store your projects in, let’s call it “C:\projects”. Make it a current folder in the command prompt. Let’s say we want our app to be named “HelpinatorDocs”. Run the following command to create app folder structure for it:

cordova create helpinatordocs com.helpinator.docs HelpinatorDocs

Now you have “C:\projects\helpinatordocs” folder with a prototype app in it. We are about to generate an Android app so we need to add Android as a platform to our app. Go to the “C:\projects\helpinatordocs” folder in the command prompt and run the following command:

cordova platform add android

Now our app is ready to be compiled into an “apk” package.

Note that there’s a “C:\projects\helpinatordocs\www” folder. This is where we need to store MobileHelp generated by Helpinator to. Run Helpinator, open your project and click “lightning bolt” icon on the main tool bar. “Batch compile” dialog appears.

Batch compile “MobileHelp”

Now we need to make some adjustments to the Cordova project config file to make our app a kiosk app.

Locate the file “C:\projects\helpinatordocs\config.xml” and open it in a text editor of your choice (NotePad++ for example).

What we need to do is to add a reference to the Cordova plugin that will do the job of transforming the app into a kiosk for us. It is called “cordova-plugin-kiosk-launcher”. There’s already a line that says:

<plugin name="cordova-plugin-whitelist" spec="1" />

Add a line that references our plugin just below it:

<plugin name="cordova-plugin-kiosk-launcher" />	

You can also change app title and description in the “name” and “description” tags.

We are ready to go. Type the following command in the command prompt while in the “C:\projects\helpinatordocs” folder:

cordova build android

It may take some time, but in the end you will get an apk of your file in the folder “C:\projects\helpinatordocs\platforms\android\app\build\outputs\apk\debug”.

You can copy this file to your device and install using apk installer. It does not require any dangerous permissions, so it should be OK. Test how your help system works on the device. After that you can select your app as a “launcher” app in “Defaut apps” settings of Android OS and it will replace the default lanucher that allows to launch apps. Basically your help system will run on the device boot, there will be no option to quit it and run anything else. Congrats, you have a self-help kiosk!

Helpinator + DITA Tutorial

DITA (stands for Darwin Information Typing Architecture) is a mature xml-based documentation authoring standard. You can read more about it on Wikipedia: https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture and it’s website: http://docs.oasis-open.org/dita/v1.2/os/spec/DITA1.2-spec.html

Helpinator allows to create DITA project from your project content with a single mouse click. This allows to use Helpinator for writing new technical content in any documentation project that is already based on DITA.

In this tutorial we will follow the procedure step-by-step, from installing DITA Open Toolkit to compiling a sample PDF document from it.

1. Download and install DITA Open Toolkit (DITA-OT).

DITA itself is just an open standard of technical content markup based on XML. The standard is huge and versatile far beyond then needs of software documentation but still you need tools to produce documents from it that you can ship to end users. Most of them are not free, with some exceptions and one of them is DITA Open Toolkit (DITA-OT).

DITA-OT tools are written in Java, so you will need Java Development Kit (not just Java Runtime) to use it, so download and install it first if it is not on your machine yet.

Then go to the DITA-OT site and download DITA-OT package for Windows. At this moment the latest version is 3.3.3 and it is available for download via this link: https://github.com/dita-ot/dita-ot/releases/download/3.3.3/dita-ot-3.3.3.zip

Unpack it into a dedicated folder, say “C:\DITAOT“.

Now you have C:\DITAOT\bin folder that holds dita.bat batch file that actually does all the job. You can run to see a brief help on parameters that it takes.

2. Export DITA from your Helpinator project

Click “Batch Compile” on the main tool bar. “Batch compile” dialog appears.

“Batch Compile” icon on the main toolbar

Scroll the list on the left down to DITA output and double-click it to add to the project.

Set “Save to” to the folder where you want to store your DITA project to. Say, “C:\Project\help\dita“.

Helpinator Batch Compile – DITA

Click on lightning bolt icon. This will create all DITA project files in the specified directory.

3. Create output using DITA-OT.

Now we can proceed to generating desired user content. Let’s say we want to create a PDF file from our DITA project files. You can open command line and run dita.bat with required parameters OR you can use a GUI tool that we created for you, called “DITA Open Toolkit Launcher“. It is a GUI wrapper around dita.bat that allows to create batch projects using visual editor, store, run and re-run them with less effort. You can download it here: https://www.helpinator.com/downloads/ditaotlauncher.zip

Download and install DITA Open Toolkit Launcher, then run it. You can see the list of formats on the left, double-click “PDF” in it, it will add PDF output to the project. Below the project items list there are item properties where you can select source file and output folder paths. Source in our case is “C:\Project\help\dita\main.ditamap” (the main bookmap generated by Helpinator), set output folder to “C:\Project\Help\PDF\“.

DITA OT Launcher PDF params

Now click “Run” on the main tool bar. For the first time it will ask to select path where dita.bat file is. In our case it is “C:\DITAOT\bin\dita.bat“. Then the tool will launch dita.bat with required parameters and produce PDF file in the output folder.

DITA OT Launcher Options
DITA OT Launcher Log

Version 3.21: Introducing WebHelp-Bootstrap

For a long time JQueryUI and it’s add-on components were the foundation of WebHelp output, generated by Helpinator. But times are changing, JQueryUI is not a major framework no more, and UX expectations of web-based documentation changed dramatically, now there’s no need to mimick CHM help with web components. Because of this we decided to add a new output – WebHelp-Bootstrap. It’s a web help system based purely on Bootstrap framework so if your project is built on Bootstrap your documentation generated with Helpinator will match dev stack used by the project or website and you do not need to add unnecessary dependencies.

Helpinator’s own WebHelp from this moment runs on it too: https://www.helpinator.com/webhelp/

WebHelp 2 is now renamed to “WebHelp-JQuery UI” so webhelp output names now match the framework used.

To compile WebHelp-Bootstrap:

  • click “B” icon on the main toolbar
  • or Main Menu->Tools->Compile WebHelp->WebHelp-Bootstrap
  • or add “WebHelp-Bootstrap” to the batch.

Publishing GitHub Pages from Helpinator

GitHub has a nice feature called “GitHub Pages” that allows you to create a nice looking static website from markdown files in your repository.

Helpinator allows to generate required markdown files so you can publish your project end user documentation using GitHub pages in a matter of seconds.

In this tutorial we will create and publish GitHub pages from Helpinator.

First, go to your GitHub account and create a repository for dicumentation. You can skip this step if you wish to add documentation to an existing repository.

Create a repository for documentation

Now you need to clone the repo to your local PC.

Run command prompt, change the folder to our documentation folder, say “C:\Project\Help” and call git:

git clone https://github.com/DmitriPopov/helpinator-github-pages.git

This will create a folder “helpinator-github-pages” in “C:\Project\Help” folder. Browse to it and create “docs” subfolder, this is where we will publish our documentation.

Now launch Helpinator and click lightning bolt icon on the main tool bar.

“Batch compile” dialog appears.

Batch compile

Browse the list of the left to “Github Flavored Markdown” and double-click it to add a new batch item.

Set “Save to” path to the docs folder in our cloned repo folder. Click “Settings”.

GitHub settings

Select “Prepare GitHub Pages source files”, click “OK”.

Now click the lightning bolt icon and Helpinator will generate all required project files.

Now we can commit documentation files generated by Helpinator to our repository.

Open command prompt again, browse to the “docs” folder inside the cloned repository folder and run the following commands:

git add --all
git commit -m "First version"
git push

Now we can open our repo on GitHub and proceed to repo settings:

Click “Settings”

Scroll down to “GitHub Pages” section.

GitHub pages section

Select “master branch / docs folder’ as the source. And then pick a theme of your choice that will be applied to your pages.

When everything is ready, the top of “GitHub Pages” section will show a link to your GitHub Pages website:

The link to the result

The result of this tutorial is available here: https://dmitripopov.github.io/helpinator-github-pages/

ReadTheDocs.org (reStructuredText) and Helpinator

ReadTheDocs.org is a cool service for delivering your online documentation to end users. It is based on reStructuredText, a plain text markup language that have a lot in common with Markdown. But, instead of learning yet another markup language to use the power of ReadTheDocs, you can just export all required files in reStructuredText format right from Helpinator.

In this tutorial we will publish Helpinator help file to ReadTheDocs.org.

ReadTheDocs pulls source files from version control systems, and we will use GitHub for this tutorial.

First, register with GitHub if you haven’t done it yet.

Now let’s create a repostitory for our documentation.

Create a new repository

Let’s say we have a documentation folder on our local PC named “C:\Project\help\” . Let’s clone our repository into it. Open command prompt, then change the folder to it and clone the repo:

git clone https://github.com/DmitriPopov/HelpinatorReadTheDocs.git

“HelpinatorReadTheDocs” folder appears in the “C:\Project\Help” folder. It is empty at the moment.

Now srart Helpinator, open the project and click on the lightning icon on the toolbar to open batch compiler. Scroll down the left list to “ReadTheDocs” and double click it to add to the batch. Then select batch item properties accordingly. We are about to write reStructuredText to “C:\Project\Help\HelpinatorReadTheDocs” folder.

Batch compile – ReadTheDocs

When everything is ready click lightning icon on the batch compiler toolbar. Helpinator will generate project files.

Now get back to command prompt, go to” C:\Project\Help\HelpinatorReadTheDocs” folder and run the following git commands:

git add --all
git commit -m "First version"
git push

Upon completion the repo will contain all project files.

Now go to ReadTheDocs.org and register there with your GitHub account, it will allow the service to access your documentation repository seamlessly.

After registration you will be taken to “Import project” screen, click “Import a Project”.

Click “Import project”

ReadTheDocs will ask you to choose a repo with documentation, click “+” sign next to it:

Select a reposiprovidtory to import
Provide project details
In seconds your documentation will be ready

You can then click “View Docs” to view your documentation.

This is what we have as a result: https://helpinatorreadthedocs.readthedocs.io/en/latest/

Knowledge Base for Context-Sensitive Help

Check out this post to know how to generate a static HTML knowledge base for your website that consists of step-by-step guides.

Let’s consider we already put this knowledge base to our website, you can see it here: https://www.helpinator.com/samplekb/

Now we can turn this knowledge base into a context-sensitive help file using MajorMindHelp and “Generate MMH wrapper” feature of Helpinator.

MMH wrapper is generally a MajorMindHelp help file that has no content in it and instead references HTML pages that are stored on an external website.

Basically the process is similar to the same that allows to turn a WordPress site into a context-sensitive help system for desktop applications described in this post: https://www.helpinator.com/blog/2019/09/10/wordpress-for-context-sensitive-help/.

Let’s say the generated knowledge base is in “C:\Project\help\kb” folder. If so, this folder should contain “_meta.xml” file generated along with the knowledge base. If it is not you should check “Create _meta.xml file when possible” option in the project settings.

Now select Main Menu->Tools->Generate code->Generate MMH wrapper for output.

Generate MMH Wrapper for a Knowledge Base

Save to – this is the full name of the mmh help file we are going to generate.

Base URL – base url of the knowledge base published on your website.

Path to the folder with “_meta.xml” file – the path to the generated by Helpinator knowledge base.

Select languages you’d want to add to the MMH file in the “Languages” list.

Knowledge base has it’s own very specific navigation, so we will not show any additional UI elements.

Now click “OK” and wait for the “Done!” message. Now you have a “.mmh” file that you can pass as a parameter to the MajorMindHelpViewer and open articles with specified context ids.

You can download and run this compiled demo to test it: https://www.helpinator.com/downloads/kbhelp.zip

Note that you also need to download and install MajorMindHelpViewer: https://www.helpinator.com/download.html#majormindhelp

How to Create a Knowledge Base With Step-By-Step Guides

In this tutorial we will cover two interesting features of Helpinator at once. The first one is called “Step-by-step guides“. It allows to define a sequence of actions or slides, each with a screenshot (optionally annotated) and text comment. You can then embed guides into topics and Helpinator will render them into output format accordingly to it’s specifications. Some output formats (like DITA or LiteHelp for example) support this content type out of the box, others, like GitHub markdown, require “emulation”.

Static Knowledge Base that Helpinator generates supports step-by-step guides and renders them as a user-controllable slideshow. It allows you to create knowledge bases for your company that contain easily understandable and navigatable procedures.

0. Planning a Knowledge Base structure

Helpinator has a versatile feature called Knowledge Base Profiles that allow to precisely define KB structure over Table of Contents created for tree-oriented outputs like user manuals. This is called “manual” mode. For this tutorial we will stick to “automatic” mode that just uses top-level topics as categories and all subtopics become articles in that category. The purpose of this tutorial is to create a Knowledge Base only, so we can design Table Of Contents with that in mind. Actually we can cteate ToC right when we create the project with ToC prototyping.

1. Creating a step-by-step guide

Step-by-step guides in terms of Helpinator are based on images (say, screenshots). It’s the basis. There is a number of ways you can collect screenshots for your guide:

1.1. Capturing with Helpinator

Helpinator has a built-in screenshot capture tool that allows to append captured images directly to a selected step-by-step guide.

Just enter the name of the guide to be created and Helpinator will append screenshots to this step-by-step guide as you capture them.

Capture into a guide

1.2. Capturing with any other tool (like TechSmith Snagit)

In this case you can paste captured images from clipboard directly to the guide editor.

Paste screenshot into guide editor

1.3. Already captured images stored in a Helpinator image library

In this case you can just select images in the library using checkboxes and click “step-by-step” icon.

Create step-by-step guide from selected images

1.4. Already captured images stored outside of Helpinator project

Same as 1.3. but you need to add images to the library first.

Add new images to the library
Click “Add images”
Image files selected
Images are in the library

2. Write step texts and titles

Now you can select the newly created guide in the project tree view and edit step texts and titles.

Edit step text and titles

3. Insert a guide into a topic

To insert a newly created guide into the topic open the topic editor and select “Insert” tab, then click “Step-by-step” and select the guide from the list.

4. Produce a Knowledge Base

To produce a knowledge base click on “Knowledge Base” icon on the main toolbar or select Main Menu -> Tools -> Compile Knowledge Base.

The default KB settings

This dialog allows to redefine project TOC to be KB-alike with categories and topics, but in our case we can leave to the auto generator, because we were after two-level KB-alike TOC right from the start.

Click OK and Helpinator will generate a static HTML Knowledge base for you.

Check out this sample KB: https://www.helpinator.com/samplekb/