Tom Johnson on WordPress for #TechComm

Direct WordPress support is a popular Helpinator feature and a lot of tech writers now suggest WordPress as a platform for online documentation (not only for software, but for other products too). Tech writing authority Tom Johnson had recently published a post on pros of WordPress, worth reading:

http://idratherbewriting.com/2014/08/19/author-dita-publish-wordpress/

What’s coming up in version 4

Version 4 is in the oven and it will bring in some important additions:

  • More supported formats including Wiki and knowledge base systems, ResponsiveHelp for touch devices and more
  • Focus on team work with new “Team Server” and “Merged Projects” utilities.

Note that with this release we will block ALL one-year keys that were not prolonged. For a long time there was a huge grace period for those who forgot to renew updates but this time all keys more than a year old will be blocked. Sorry 🙂

As always version 4 is a free update for life-time licenses and one-year licenses that are not older than a year from the date of release.

How to use “REimport” feature

Version 3.11.4 introduces new feature called “REimport”. What is it for?

Let’s consider this scenario  – you start your help project by importing html/rtf/txt files that you already have as documentation, do some alterations, formatting, screenshots, etc and all over sudden source documents change and you have two options – copy/paste them manually or import all documents and start your help project from scratch. Sad.

But not any more. Now you can selectively import changed documents into existing topics.

First, scroll the project tree down to the “Tools” node and select “REimport” sub node.

reimport1

 

If your documents were imported with version 3.11.4 and above, “File name” and “Path” columns should be filled with paths of source documents. In our case we have old project with blank columns. Helpinator will remember selected file names for future use.

First of all check topics to import with check boxes in the first column. Then select file names to import – double click the cell next to the topic title and select file name in the dialog that appears.

When everything is set and done click “Run” button on the toolbar below “REimport” title.

How to adapt existing RTF/PDF/Print templates to new topic title styles

Version 3.11.3 allows you to define different styles for topic titles according to their levels in the topic tree. Say, you want to have topic titles of level 1 in bold, level 2 in italic and level 3 underlined – now all that is possible.

Old versions allow only one style, it is defined by formatting of pseudotag {%TITLE%}. That should continue to work, but if you want to use new feature of topic title styles you need to upgrade your template. However it is very easy to do. The overall idea remains the same, but pseudotags are now numbered to reflect levels. E.g. {%TITLE1%} for the first level, {%TITLE2%} for the second and so on. You can create a new blank project with version 3.11.3 and open “default.rtf” node to see how it is done. The image below shows how it should look like (you can set your own styles of course).

rtftitles

How to change order and hierarchy of topics quickly

Version 3.11.3 introduces new feature called “Advanced rearrange”. It allows to quickly change order, titles and hierarchy of multiple topics at once. Normally Helpinator allows to change order of topics and their position in the topic tree by dragging and dropping topics in the topic manager. It is good for a topic or two but is very uncomfortable and time-consuming when you need to change places of several topics in a large project (say, after mass-importing html/rtf files).

To activate this feature select “Topics” node and click the button shown on the image below.

 

rearrange-button

 

It opens up “Advanced rearrange” window. This window is a simple plain text editor with a topics tree converted to it’s plain text representation. Each line has a topic title and topic id in brackets at the end of the line. If a topic is a subtopic, it’s line starts with a TAB (one for level 1 subtopics, two TABS for level 2 and so on).

 

advanced-rearrange

 

What you can do here:

  1. Cut/Paste topics en masse. Select several lines with your mouse or Shift+cursor, click Ctrl+X to cut them, place cursor into their new location and click “Ctrl+V” to paste.
  2. Change levels – just insert/remove TABs at the beginning of the line. To move several topics to another level (e.g. to insert TAB into several lines) select them as told above and click “Increase Level”. This will insert TABs into several lines at once. “Decrease level” works the same way.
  3. Rename topics. It’s OK to change topic titles as long as you keep ID part at the end of each line intact.

What you CAN’T do:

  1. Change or delete topic IDs. They are used for identification, so it will cause an error.
  2. Delete topics – to delete topics please use corresponding command of the topic manager. Deleting topics here will cause an error.
  3. Add new topics – the same as with “Delete topics” issue, use “Add topics” command from the topic manager.

How to use “Batch Compile” to create different versions of your documentation

“Batch compile” feature not only allows you to compile all supported help and documentation formats using only a couple of clicks. It also allows you to compile different versions of documentation based on preset and conditional compilation described in this post:

http://www.helpinator.com/blog/2013/06/20/how-to-create-different-versions-of-documentation-from-the-same-source/

In this post we’ll use “Conditional Output” sample project from the set of Helpinator samples included with installation.

image

 

This simple demo has PRO and FREE presets and “Topic 1.1” which is to be published only when “PRO” preset is selected.

Open this sample (Welcome screen->Samples->More Samples) and click “Batch compile”.

Helpinator 3.11.1 - CUsersPublicDocumentsHelpinator Samplesconditions.hpz (Registered to Dmitri Popov)

 

1. Double-click “PDF” in the list on the left to add two “Compile PDF” tasks.

2. Enter “Save to” paths. In our case we will store two files (for Free and Pro editions respectively) into out project’s help folder. {%PRESET%} placeholder will be replaced with the selected preset name. You can also use variable names in this field.

3. Select “FREE” preset for the first task and “PRO” fro the second.

 

Batch Compile

 

Now you can click “Compile” and Helpinator will create two PDF files: “FREE.pdf” and “PRO.pdf”, the first one will go without “Topic 1.1” (as indicated by it’s “Skip topic“ condition).

How to create different versions of documentation from the same source

OK, Helpinator is a multi-format single source help authoring tool, e.g. you can create help files and documentation in different formats from the same source. But what if you need different versions of content? Say, your app has two edition: Pro and Lite with different sets of features and you need to create CHM help files for both editions. What to do? Create different help projects for each edition? NO! Use conditional output!

Conditional output is based on variables. Variable values control conditional statements, that in their turn alter output at compile time. Helpinator has special type of variables that allow to switch their values quickly. Values of these variables depend on which values preset is selected at compile time. Take a look at the “Variables” tab of project options. At the bottom of it there’s “Preset” drop-down list and commands to add, rename and delete presets. Let’s add two presets: “PRO” and “LITE”.

var1

 

Now we can add control variable that we will use in conditional statements. Let’s call it “EDITION”.

var2

 

Set it’s value to “PRO” for PRO preset and “LITE” for LITE preset.

Now when “PRO” preset is selected this variable has PRO value in it and LITE when “LITE” preset is selected.

There are two ways you can control output:

  1. Via IF directives in the topic content
  2. Via topic inclusion condition

 

First let’s see how to use IF directive. Say, our help project has “Features” topic with a list of features in it. Remember, our PRO and LITE editions have different sets of features. You can use a directive like this to make topic “Features” contain only features of LITE or PRO editions:

ifcondition

 

But that’s only one problem. Our help project also contains separate topics for each of the features and we do not want to include topics with features of PRO edition into the help file of LITE edition. This is where topic inclusion condition comes in help. Take a look at the bottom of the topic editor, there’s “Skip topic” tab. It contains “Skip when condition is FALSE” field, it allows you to set condition for topic inclusion. In our case we’ll create a condition EDITION=’PRO’ for the topics that cover features of PRO edition, so they will be included in PRO edition help file and skipped from LITE edition help file:

skiptopic

 

Hope this little tutorial will help you to get familiar with conditional compilation. Also there’s a sample project with the same name that you can access via “Samples” section of the welcome screen. Click “More samples” and select “Conditional output” from the list.