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.
Code snippets like figures are a dedicated content item in Helpinator. We made it that way to apply syntax highlight and also because in some of the outputs (Leanpub, DITA for example) code snippets must be marked correspondingly. You can paste code snippets right into the topic editor using a dedicated command and it will create a corresponding snippet in the library.
2. Slice code snippet
Sometimes you need to create a set of snippets from the same source file and it may take quite a time to crete them one-by-one. “Slice…” command makes it faster – select text, enter snippet id and click “Create”, then select another portion of text and so on…
Check your project options and see whether the “Create “_meta.xml” file when possible” is checked. In this case when you publish your content to WordPress Helpinator creates a system file that stores topic page URLs and context IDs.
Now publish to WordPress and then browse to your project folder, “wordpress” folder containing “_meta.xml” should appear there. We will need this file to generate MajorMindHelp file that “wraps” your WordPress site. Then you will be able to MajorMindHelpViewer as a context-sensitive help system with topics from your WordPress site.
In Helpinator select Main Menu->Tools->Generate Code->Generate MMH Wrapper for Output.
Save to – this is the file name to store your MajorMindHelp help file to.
Base URL – is the base URL of the documentation site. In our case it is “http://www.mydomain.com”. But it could be anything like “http://documentation.mydomain.com”, “http://www.mydomain.com/doc”, depends on where you store your documentation.
Path to the folder with “_meta.xml” file – is the path where your generated “_meta.xml” file resides. Our main project file is in “C:\Project\Help”, so Helpinator generated xml file in the folder “wordpress” next to it (“WordPress” in this case is the name of the ouput format).
When you choose the path to “_meta.xml” Helpinator shows the list of languages stored in it. You can select what languages to include into MajorMindHelp file.
Visible UI elements – you can hide some of UI elements of MajorMindHelp viewer if you do not need them. For example, you can hide “Contents” tab and use table of contents of your HTML pages. In case of Helpinator WordPress themes you can use both modes – hide “Contents” or chose to hide navigation of WordPress theme. In this demo we choose to use the Viewer’s table of contents and hide the wordpress theme navigation.
Append this text to the end of topic URLs: this field allows to specify custom text that will be added to each topic URL when requesting content from the website. In case of Helpinator WordPress themes there’s a parameter named “nonav” that allows to hide theme navigation. And this is what we want to do becuase we prefer viewer’s navigation in this demo. So we need to set nonav param to 1: “&nonav=1”.
Now click “Generate” and wait for the confirmation.
The installer will create a file extension association for “.mmh”. So you will be able to launch help files with double-click from Windows Explorer.
So browse to the “C:\Project\Help\MMHWrapper\” and double-click “wordpress.mmh”. The viewer will launch and open our WordPress site:
The viewer allows to communicate with it via Windows messaging system, so you can tell it to open the topic you need, locate a keyword, execute search or switch language. At this moment we provide out-of-the-box solution for Delphi that allows to integrate MajorMindHelpViewer into your desktop Windows app like any other help system supported by Delphi. There’s a demo on how to do it inside the integration code package: https://www.helpinator.com/downloads/mmhdelphi.zip
The viewer itself is free for commercial use, you can redistribute it along with your application, as long as you use outputs generated by a licensed version of Helpinator.
If you need to integrate context-sensitive help system of MajorMindHelpViewer with another development tool, please drop a line to email@example.com and we will add it.
We will add more content sources soon, so if you need to use Confluence or Zendesk for context-sensitive help, please contact us too.
In most cases error messages that you get when you publish Helpinator content to WordPress are informative and easy to fix. Except two cases: “Access denied” and “Moved permanently”.
1. Access denied
Nowdays there are many shared hosting providers that block WordPress XML-RPC access by default. This is why you get this error message. There are two possible solutions for this problem – contact your hosting provider and ask them to allow XML-RPC or just rename xmlrpc.php file that is in the root folder of your WordPress installation to, say, xmlrpc123.php.
Helpinator allows to specify “Endpoint” in the “Publish to WordPress” settings dialog. Essentially it is the name of the xmlrpc.php file. So, in our case you can set it to xmlrpc123.php.
2. Moved permanently
Typically this problem arises from WordPress caching plugins, especially WP Super Cache and W3 Total Cache. The only way to fix it is to temporarily disable caching plugins before you publish content and then enable them back.
Upon completion of WordPress setup you get to the Dashboard. Go straight to the “Plugins” section, we need to install 2 plugins:
Helpinator Quick Publish plugin – extends WordPress XML RPC API so it becomes possible to publish pages in “packages”, not one-be-one which is time-consuming.
WP-Reset plugin. In case you f-ck up with content, it’s better to reset your WordPress to a state of brand new than to remove piece-by-piece content that is messy.
To install a plugin:
1. Go to “Plugins” section of the Dashboard
2. Click “Add new” button at the top. Then start typing “Helpinator” into the “Search” field on the right
3. Click “Install now” then “Activate”
Repeat the steps for “WP Reset” plugin.
Now we need to install Helpinator documentation theme. You can omit installing Helpinator theme if you wish the published content to fit into your current theme – not a problem, Helpinator will do that. However it is more convinient to browse technical documentation in a specialized layout, and this is what Helpinator themes do.
Extract theme files to WordPress themes folder, in our case it is “C:\xampp\htdocs\www\mydomain.com\wp-content\themes\“, complete theme folder.
Helpinator WordPress online documentation themes are made to be child themes of your main theme, but you can use them as standalone themes too. However, by default, there’s a setting that this theme is the child theme of “twentynineteen”, the default WordPress theme. If you use another theme, or you want to use Helpinator theme as a standalone, you have to make alterations to styles.css file.
Theme Name: Helpinator Modern
Theme URI: http://www.helpinator.com
Description: WordPress theme for use with Helpinator
Author: Dmitri Popov
Author URI: http://www.dmitripopov.com
Tags: HTML5, CSS3
License URI: http://opensource.org/licenses/mit-license.php
See the “Template:” parameter that points to “twentynineteen” theme. Remove theme name if you plan to use Helpinator theme as a standalone theme, or change “twentynineteen” to the name of template you want other parts of your WordPress site to use.
All Helpinator themes only add one page template named “HelpinatorDocTemplate” (helpinator.php) that you need to choose as a page template when publishing content from Helpinator.
Let’s select Helpinator theme as our WordPress site theme. Open WordPress Dashboard and select “Appearance->Themes” from the left sidebar menu.
Click on “Helpinator Modern” then “Activate”.
There’s one last thing left to do before we preceed to publishing. We need to add an empty root page for our documentation. You can skip this step if your create a documentation-only website, in other cases we will need to filter only documentation pages to show in our documentation Table Of Contents, and the easiest way to do it is to make all documentation pages children of one root page. So open “Pages” section of WP admin dashboard:
We don’t need any specific content, so just name the new page “Documentation”, then click “Publish”.
Now the initial setup is complete and you can move on and try to publish something from Helpinator.
Run Helpinator, open your project file and click “WordPress” icon on the toolbar:
Click “+” sign to add a new WordPress site profile. Let’s name it XAMPP since we are going to publish to our tests site.
We do not use SSL on our test site so do not check it.
Leave “Endpoint” field blank too, it is for complicated cases mostly. For example, when you rename your xmlrpc.php file to avoid problems or when your WordPress installation is in a subfolder (say “blog”), so in this case “Endpoint” should be “/blog/xmlrpc.php”
Fill your WordPress username and password. Note that Helpinator does not store your passwords, you will need to enter it on each session.
Now we need to get the list of page templates and select “HelpinatorDocTemplate”. Leave “Parent” page empty because we do not want our docs to be attached to existing page. Check “WP site runs on Helpinator WordPress theme”, it will allow all dynamic content like step-by-step guides to appear correctly. They will work with other themes too, but as a static content only. Check “WP site has enabled Helpinator Quick Publish Plugin” because we have it. This will speed up publishing.
Now click “Save profile” – this will save you time because you will be able to use again the settings provided.
Click “Publish”. Note that it may take some time to finish.
When Helpinator finishes it will ask you to save your project. This is needed to store page ID’s of the published topics so Helpinator will be capable to update pages when you hit Publish button again and not create new ones.
When done head over to WordPress admin dashboard again. We need to do some settings customizations for our project to appear correctly. Remember empty “Documentation” page that we created to be the root page of documentation? Now we will set it to be the starting page of documentation theme, so WordPress will show only documentation pages in the documentation section.
Then select “Helpinator settings”.
Select our “Documentation” page as the TOC root page, then click “Publish”.
Now we can preview our documentation section. From the “Pages” section of WordPress admin dashboard, hover the mouse cursor over one of the pages and click “View”.
The page might look like this:
Now let’s take some time and create a test navigation for our site. By default “twentynineteen” template does not have navigation so the rest of your site is unaware about the existence of the “Documentation” section.
Enter “mainmenu” as the menu name and click “Create Menu”.
We are creating the primary site menu so select corresponding checkbox.
Select “View all” tab, then select “Home” page and the first page of our documentation (note that it’s NOT the “Documentation” page). Then click “Add to Menu”.
Now click on our first documentation page to roll down the settings and change navigation label to “Online Documentation” – this way it will appear in the menu. Then click “Save Menu”.
Now open the front page of our site. It should look like this, note the link to documentation section is now in the menu at the top of the page.
See that the rest of the site uses twentynineteen theme while documentation section uses Helpinator theme.
That’s all for this tutorial! Thank you for reading!
XAMPP is an incredibly convinient development stack for Windows consisting of apache, php, mysql, mariadb and perl. You can use it to test your WordPress site publshed from Helpinator before releasing it to public.
Run the installer and follow steps. When asked for a folder enter “C:\xampp” or another folder OUTSIDE of “Program Files”.
When the installer finishes you are allowed to run XAMPP Control Panel which provides an easy way to Start/Stop services and alter configurations.
But before we start anything let’s add our testing domain to Apache (because we wll have to restart it anyway). To add a new domain you will need to perform a set of actions (create html files folder, alter apache config and Windows hosts file so you can access your site by domain name from your web browser). But we wrapped all that into a handy tool that you can use to add domain names with a single click. Download it using this link: https://www.helpinator.com/downloads/xamppaddsite.zip
Now we can launch services, Apache and MySQL in particular. Click “Start” button next to the service name.
Click “Admin” button next to “MySQL” service, it will open PHPMyAdmin in your webbrowser. We will add a new database for WordPress using it.
Now click “Databases” tab. Enter “wptest” below “Create database” and click “Create”.
There’s “wordpress” folder in this package, extract files from this folder into our new site root, located at C:\xampp\htdocs\www\mydomain.com
Now we need to create WordPress configuration to continue. Locate wp-config-sample.php and rename it to wp-config.php. Open this new file in any text editor and set the following lines
// ** MySQL settings - You can get this info from your web host ** //
/** The name of the database for WordPress */
define( 'DB_NAME', 'wptest' );
/** MySQL database username */
define( 'DB_USER', 'root' );
/** MySQL database password */
define( 'DB_PASSWORD', '' );
We set DB_NAME to wptest database that we created, DB_USER to root and DB_PASSWORD to empty string. Of course in production server settings like this are a suicide, but we only need it for local testing.
Now you can delete index.html file that was created automatically by XAMPPAddSite as a stub. Then open your web browser and navigate to your domain name (mydomain.com in our case). WordPress installer appears.
Helpinator allows to generate ASCIIDoc source file (with .adoc extension) that you can use in your ASCIIDoctor documentation toolchain or just employ to create HTML using beautiful templates that this generator provides. In any way you need to install ASCIIDoctor on your Windows system and given it’s Ruby origins it may become quite a task for a novice.
Good news is that there’s a JS-port of ASCIIDoctor that you can install via npm (node package manager) and use from the command line. Here are the steps.
1. Download Node.Js dsitribution package from https://nodejs.org. It’s better to choose installer over other variants, because it will execute all required tasks like adding node to the PATH variable automatically.
2. Run the installer and follow the instructions. It’s better to choose the path outside of Program Files folder.
Finish the installer and reboot your machine just in case.
Now you have Node Package Manager on your system and you can use it to install ASCIIDoctorJS.
3. Open command prompt and change current path to C:\nodejs (the folder where node.js resides on your system).
Now let’s install ASCIIDoctor via command line using npm:
npm i asciidoctor --save
npm i -g asciidoctor.js asciidoctor-cli
This will create asciidoctorjs.cmd file in node.js folder that will be available from command line.
4. Now let’s produce some ASCIIDoc sources from our Helpinator project. Select Main Menu -> Tools -> Batch Compile and add “ASCIIDoc” output, then specify folder path to save output to.
Click on lightning bolt icon and Helpinator will create .adoc file and images folder in the path specified.
Now we can get back to command line, change current folder to C:\Project\Help\ASCIIDoc and run asciidoctorjs to create HTML5 file from “Helpinator.adoc” file generated by Helpinator:
You will see generated .html file next to your .adoc file when the command finishes execution. Open it and enjoy impressive design work done for ASCIIDoc.
If you are too lazy to follow the procedure above, there’s a compiled source file of Helpinator help system in ASCIIDoc format on the “Download” page under “Sample Documentation” section.
None of us are perfect. And from time to time we write imperfect documentation. The documentation that is not bad in any sense but is just not 100% perfect. A perfectionist will go into all-out complete rewriting rage and will write something that is for 1% more perfect than it was. But a real writer will do the refactoring. Helpinator has some tools to help you with that.
1. Mighty TOC rearranger.
Helpinator allows to rearrange topics using drap-and-drop, but that is time-consuming. You can rearrange TOC like a plain text document using “Advanced rarrange” command.
2. Merge topics.
“Merge topics” command allows to combine several topics into a new topic. The new topic will be appended to the end of TOC.
3. Refactoring->Extract topic / Extract subtopic
Topic editor has a pop-up menu that appears when you right-click in the editor area.
Both commands allow to create new topic from selection. The former appends new topic to the end of TOC, the latter create a new subtopic of the current topic.
“Add topic” dialog appears, it allows to specify properties of the new topic that will be created from the selection.
4. Refactoring->Move selection to topic / Copy selection to topic
These two commands are in the same menu as pevious two. The only difference is that they do not create a new topic but instead allow to move/copy selection to existing topic. When you select this command, “Select topic” dialog appears that allows to choose topic to move/copy content to.
See also other posts about technical writers productivity: