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:
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.
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.
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 capture – Paste 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.
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
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.
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:
A GitHub account
A LeanPub account
Helpinator installed on your system, click here to download the installer (trial version will do the job).
First of all, let’s get to the GitHub and create a repository for our book source
Give it a meaningful name and description.
Now we can test it and clone the repository into our desktop. Let’s run some command line magic:
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.
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.
Now we can proceed to Leanpub and create a book in your account.
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.
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"
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”
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.
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.
+ 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