3. Knowledge Base
3. Knowledge Base
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:
What we need to accomplish this task:
To install Node.js go to https://nodejs.org/en/download/ and select installer for Windows version that you use.
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:
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.
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!
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.
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“.
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\“.
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.
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:
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.
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.
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”.
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:
Scroll down to “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 result of this tutorial is available here: https://dmitripopov.github.io/helpinator-github-pages/
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.
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.
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”.
ReadTheDocs will ask you to choose a repo with documentation, click “+” sign next to it:
You can then click “View Docs” to view your documentation.
This is what we have as a result: https://helpinatorreadthedocs.readthedocs.io/en/latest/
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.
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
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.
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.
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.
1.4. Already captured images stored outside of Helpinator project
Same as 1.3. but you need to add images to the library first.
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.
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.
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/