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:

md leanpub
cd leanpub
git clone

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:

The source repository on GitHub:

Download Helpinator:

Helpinator 3.20

  • Added: New LeanPub output
  • Added: New ASCIIDoc output
  • Added: New DITA output
  • Added: New DocBook output
  • Added: WordPress plugin to publish faster
  • Added: 2 new WordPress themes
  • Added: Option to create MajorMindHelp wrappers around any HTML-based output
  • Added: New LiteHelp output
  • Added: Own help system moved to LiteHelp
  • Added: LiteHelpViewer.exe included into the installer (you can also download it separately)
  • Added: New “Plain Text” output to create old school plain text readme files
  • Fixed: Bugfixes

Helpinator 3.17

+ Added:  Now you can save batches to project files and launch them using main  tool bar “Compile All” drop down with a single click
+ Added:  New “Topic Keywords” dialog allows to add/edit topic keywords quickly
+ Added:  New “Paste screenshot from Clipboard” editor command
* Memory usage imrovements