Productivity Tools For Technical Writers Part 3

1. Paste code snippet

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.

Pasted code snippet

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…

Slice code sample

WordPress for Context-Sensitive Help

Publishing your end user documentation online has a number of advantages:

  • it improves your SEO and attracts new visitors
  • it is easy to update

However when you develop a desktop app you have to either duplicate content in your context-sensitve help system or get rid of this system and just open your website when a user presses F1.

MajorMindHelp solves this problem. It allows to turn any HTML-based content published on your website into context-sensitive help, including content published to WordPress.

Before proceeding please read this tutorial on how to publish your end user documentation to WordPress: https://www.helpinator.com/blog/2019/09/07/wordpress-for-online-documentation-how-to-use-helpinator-plugin-and-documentation-themes/

Check to create “_meta.xml”

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.

Generate MMH Wrapper

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.

Next step is to download and install MajorMindHelpViewer from our “Downloads” page: https://www.helpinator.com/download.html#majormindhelp

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:

WordPress site in MajorMindHelpViewer

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 office@majormind.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.

Troubleshooting WordPress

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.

Setting “Endpoint” to the renamed xmlrpc123.php file

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.

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

If you missed the post about setting up your own local testing environment for WordPress check it out before reading this one: https://www.helpinator.com/blog/2019/08/27/setting-up-xampp-to-test-wordpress-site-on-windows/

Upon completion of WordPress setup you get to the Dashboard. Go straight to the “Plugins” section, we need to install 2 plugins:

  1. 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.
  2. 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

Plugins – Dashboard

2. Click “Add new” button at the top. Then start typing “Helpinator” into the “Search” field on the right

Helpinator plugin

3. Click “Install now” then “Activate”

Activate plugin

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.

Open Helpinator downloads page and scroll to “WordPress” section: https://www.helpinator.com/download.html We will use “Modern” theme for this tutrorial, so download it.

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
	Version: 1.1
	Author: Dmitri Popov
	Author URI: http://www.dmitripopov.com
	Tags: HTML5, CSS3
        Template: twentynineteen
	License: MIT
	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.

WordPress themes

Click on “Helpinator Modern” then “Activate”.

Activate Helpinator Theme

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:

“Pages” section, “Add New”

We don’t need any specific content, so just name the new page “Documentation”, then click “Publish”.

Empty “Documentation” page

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:

“Publish to WordPress” on the main 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.

Fill in the “Host” name, in our case it is “mydoman.com” from this post: https://www.helpinator.com/blog/2019/08/27/setting-up-xampp-to-test-wordpress-site-on-windows/

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.

Fill in WordPress site details and check connection
Connection OK

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.

Page template, parent page, etc.

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.

Select “Appearance”->”Customize”.

Appearance->Customize

Then select “Helpinator settings”.

Helpinator theme settings

Select our “Documentation” page as the TOC root page, then click “Publish”.

Select “Documentation” as the root page

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”.

Preview the page

The page might look like this:

Publlished topic page

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.

Select “Appearance”->”Menus”.

Appearance->Menus

Enter “mainmenu” as the menu name and click “Create Menu”.

Create a new menu named “mainmenu”

We are creating the primary site menu so select corresponding checkbox.

The primary menu

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”.

Alter navigation label

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.

Front page menu

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!

Setting up XAMPP to test WordPress site on Windows

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.

Head over to XAMPP site (https://www.apachefriends.org/index.html) and download Windows installer.

XAMPP website

Run the installer and follow steps. When asked for a folder enter “C:\xampp” or another folder OUTSIDE of “Program Files”.

XAMPP installation folder

When the installer finishes you are allowed to run XAMPP Control Panel which provides an easy way to Start/Stop services and alter configurations.

XAMPP control panel

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

XAMPP Add site tool

Now we can launch services, Apache and MySQL in particular. Click “Start” button next to the service name.

XAMPP Services Running

Click “Admin” button next to “MySQL” service, it will open PHPMyAdmin in your webbrowser. We will add a new database for WordPress using it.

PHPMyAdmin

Now click “Databases” tab. Enter “wptest” below “Create database” and click “Create”.

phpMyAdmin create database

Now go to WordPress site and download fresh WP.

Download WordPress

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.

WordPress installer

Now you can complete your WordPress installation.

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

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.

Node.js installer
Set path for node.js

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.

Batch job to compile ASCIIDoc

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:

asciidoctorjs Helpinator.adoc

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.

Refactoring documentation

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.

Advanced rearrange
Advanced Rearrange Dialog

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.

“Merge topics” command

Merge topics dialog

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.

Editor right-click menu
Add topic dialog

“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.

“Select topic” dialog

See also other posts about technical writers productivity:

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



Productivity Tools For Technical Writers Part 2

1. Cloned images

Helpinator allows to add callouts to screenshots/figures. Sometimes the screenshot is not that big, but the callouts are large or are in numbers. Another but similar situation is when you need to eplain different tasks based on the same screenshot. In both cases you have to double the image but it is a nightmare in terms of maintenance. The problem is so big that exprienced technical writers even try to avoid pictures whenever possible.

Helpinator solves this problem with “cloned” image. You can create one “donor” image and then define any number of “clones” that will inherit the screenshot but will have their own callouts. When the time comes to update the screenshot you only need to update one “donor” image.

Create a cloned image
New cloned image

2. Active region

Active region is a feature that you can use with cloned images. In many cases there’s no need to show entire screenshot in a cloned image, instead you only need a part of it. That’s where “active region” comes in hand. You can define a rectangular area on your image that will be rendered in the output instead of the whole large picture.

Change active region
Active region of a cloned image

Note that there’s a rectangular region on the last image selected. This is the active region of the cloned image, so we will see only “Tools and Reports” section of UI in the output.

3. Integrate with 3rd party screenshot capturePaste screenshot from clipboard

There’s a huge number of high quality screenshot capture tools available on the market, and you can use any of them as a companion to Helpinator. Screenshots/Figures are a dedicated content item in Helpinator, but storing screensots captured in another tool to file and then importing them to Helpinator is a pain. Instead there’s a dedicated editor command for it – “Paste screenshot/figure from clipboard”. It is available in “Image library”, topic editor and step-by-step guide editor.


Paste screenshot into the editor
Paste screenshot/figure from clipboard
Paste image into the image library
Paste new step

Productivity Tools For Technical Writers Part 1

Helpinator is not a big player like Help&Manual or RoboHelp or Madcap Flare, it’s a tiny tool compared to them, so right from the start it was focused on handy features that solve one specific problem at a time. And a time spent on repetetive tasks while maintainig a documentation project is the problem that we were trying to address. Here’s what we did:

1. Quick project navigation

Large projects tend to be hard to navigate. The project tree becomes too large and it takes a lot of time to switch from one content piece to another. Helpinator allows to do it quick (of course if you can recall at least partially the ids of the items you look for)

1.1 Tree filter

Above the project tree there’s an edit field with a looking glass icon. Typing something it it causes the tree to show only content items with names that contain the text entered.

On the left there’s a set of icons that allow to filter in/out whole sections of the project tree (like images, code snippets, etc).

1.2 Go to item (Ctrl-F12).

If filtering the whole tree is not a best choice for you at the moment, you can just go to the content item quickly. Press Ctrl-F12 and the “Quick jump to item” dialog will let you to filter out and select an item to go to.

1.3 History – Next/Previous

Ctrl+Left cursor key and Ctrl+Right cursor key allow to navigate history of items you visited during this session.

2. Phrase Expander

Phrase expanders are a category of writing productivity tools that allow to type less. You can define your most common phrases thay you use often then define a shortcut that will paste the corresponding text into the editor.

Helpinator has a built-in phrase expander that works via Ctrl+Space key combination. To define shortcuts open phrase expander settings via Main Menu->Tools->Phrase Expander Settings

Phrase Expander settings
Press Ctrl+Space to replace the shortcut

3. Quick image finder

Large projects have a lot of images in the library and becomes excessively hard to insert images into topics using just drop-down menu. But there’s a command in the “Insert Figure” menu that acts pretty much like “Go to item” command, but instead inserts an image into the editor.

“Quick search for an image” menu
“Quick search for an image” dialog.

LeanPub Tutorial: Publishing Your Book Using Helpinator

LeanPub is an excellent ebook and ecourse publshing platform that supports authors on every step. You can author books in Leanpub-flavored Markdown or in their own markup language called Markua, and the book project structure is VERY simple and straightforward so even a novice in writing/authoring is capable of doing it.

Helpinator allows you to generate Leanpub-flavored Markdown topic files and create all required project files to generate a ebook, simplifying the process even further.

In this tutorial we will publish Helpinator User Manual to the LeanPub platform, step-by-step.

You will need:

  1. A GitHub account
  2. A LeanPub account
  3. Helpinator installed on your system, click here to download the installer (trial version will do the job).
  4. Git client

First of all, let’s get to the GitHub and create a repository for our book source

Click “+” and select “New repository”

Give it a meaningful name and description.

New GitHub repository

Now we can test it and clone the repository into our desktop. Let’s run some command line magic:

C:
md leanpub
cd leanpub
git clone https://github.com/DmitriPopov/helpinatormanual

This will create a local copy of our repository.

Now we need to create a “manuscript” folder in it. This was LeanPub will know where the book source is.

cd helpinatormanual
md manuscript

Now let’s get back to GitHub UI. We need to add LeanPub as a collaborator to our repository so it will be able to access it.

Add Leanpub as a collaborator

Now we can proceed to Leanpub and create a book in your account.

Click “Create a book”
We want a book
Provide book title and URL
Our book is technical
Helpinator will generate the text, but for Leanpub you write it by yourself
We store it on GitHub
FREE plan is OK at the moment
Click “Add to plan”
The welcome page of the book

The project infrastructure is ready. Now we can generate the book source.

Run Helpinator and open the project file. Now click on the “Lightning bolt” icon on the toolbar or select Tools->Batch Compile.

Batch compile dialog of Helpinator

Helpinator will export content to the folder specified.

Now we will get back to our folder and commit files to GitHub.

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

These commands will put our freshly exported LeanPub content to the repository.

Now the best part – we can go to LeanPub and request a book preview. Be careful with that, because the FREE account has certain limitations on the number of times you can request a preview.

Head to LeanPub, select your book in the menu and click “Preview or Publish” – “Preview new version”

“Preview new version” menu command

Select “Full preview” and click “Create preview”.

The process may take some time, so you can leave this page. You get a notificaction via email when the book preview is ready.

Preview your book

You can download book files and if you are satisfied with them you can choose “Publish new version” from the menu and LeanPub will update files availble to your readers and book purchasers.

Here’s the result of this tutorial: http://leanpub.com/helpinatormanual

The source repository on GitHub: https://github.com/DmitriPopov/helpinatormanual

Download Helpinator: http://www.helpinator.com/downloads/helpinator3professional.zip