How to write user documentation for software: best programs and services

It goes without saying that drafting technical documentation for a product is no less complex than writing code for it. Developers often put off the task of writing user documentation because they consider it time-consuming, costly or downright boring.

Nevertheless, writing documentation for software or a web service is an important part of the development process. If the process of providing documentation for your product causes you trouble, this overview is for you.

We will provide you with information about the market’s best user documentation tools that will turn this impossible task into an easy walk.

— But wait, wouldn’t technical documentation be overridden by technical support?

Tech support can let you down – either accidentally or due to the incompetence of employees. Rude technical support workers are also quite common. What is more, sometimes tech support lines are overflooded and users simply cannot reach them.

Such cases have a negative impact on the reputation of the company and it is better to secure yourself in advance – create a thought-out user manual.

However, drafting technical documentation for software or services is never an easy task. You need to thoroughly study the program, predict what difficulties users may encounter, describe all the features of the product, create a logical structure, add enough screenshots and explanations. When everything is ready – post the manual on your website and/or implement it into your software to help the users.

Such documentation is often written in text editor, but it greatly complicates an already lengthy process. Specialized software has many features to provide for simplification. For example, the ability to structure future documentation, create sections, make explanations on screenshots, export content into various formats (HTML, CHM, PDF) and much more. Today we’ve chosen out top 5 programs and services for creating user documentation. We consider them best suited for the role.

5 Best Help Authoring Tools

1. Dr.Explain

Dr.Explain is one of the few programs that automate the process of creating user documentation. When drafting documentation, the writer has the task of showing visually how everything works and wh ere everything is located. To do that, they ins ert screenshots with explanations of the program interface elements into the manuals. Dr.Explain has a special tool that highlights all of the important elements on a screenshot, such as buttons or fields, and adds annotations {callouts) with explanations. All the writer has to do is to provide descriptions.

The second thing that catches your eye when exploring the capabilities of the program is the built-in documentation templates. It's always easier to work from a template, look at the example documentation, supplement and modify it to suit your product. This is exactly what Dr.Explain offers. There are three documentation templates in the program: the user manual for the software, the user manual for the web service, and the corporate knowledge base template.

No matter how well the software helps you write documentation, the ultimate goal is to publish the content on the product’s website and integrate it into the product so that users can read your manual. Dr.Explain allows you to export your project into popular formats: HTML for the website, CHM for built-in help notes and PDF. Dr.Explain allows you to work in teams via a cloud service or a local server. In the program, you can se t sections to "degree of readiness", in this way you can control the process of writing documetation.

The program has a convenient and smart WYSIWYG editor, the ability to customize the style of your documentation, the ability to customize context-sensitive date.

Pros:
+ Large list of features that allow you to create a quality and complete user manual or knowledge base.
+ Automatic annotation of screenshots
+ Documentation templates

Cons:
- No web interface
- No version for Mac and Linux
- No export into ePub, markdown and other specific formats

2. HelpnDoc

The main plus of HelpnDoc is the ability to export to an unimaginable variety of formats, thus the ability to create multi-format documentation.
Creating documentation for a mobile app? Do your users need to read documentation from an e-book? Need to create documentation for a product on Linux, Ubutu, UNIX? This program will help.

Powerful media library system. All media elements such as images, videos, documents, HTML code snippets are managed by the library: these media elements can be reused many times.
Need to change one picture but it's been posted in the documentation dozens of times? Just upd ate the library element, and it will be distributed to all features that use it.

With the script editor, you can easily automate repetitive tasks and focus your attention on complex ones. Do you need to change the order of topics? Replace all the items in your library? Run the script editor, enter a few instructions, click "Execute", and then some of the routine work will be done automatically.

HelpnDoc analyzes the written documentation and can show you broken links, links with errors, missing or duplicate multimedia elements. All such errors can be seen in one place (analyzer) and you can start fixing them right away.

Pros:
+ Ability to create multi-format documentation.
+ "Scripts" significantly simplify and speed up the process of writing a manual
+ Smart analysis and validation of your project.

Cons:
- Relatively complex user interface.

3. ClickHelp

Clickhelp, unlike the previous two, is not a program, it's a web service for creating documentation.

The service is useful for products that want to go international. ClickHelp has the ability to translate your manual into any language, with the help of Google, of course. Importantly, by changing the source text, the changes will appear in all translated versions in those same languages.

Imagine that users open a manual and try to find something on a certain topic. They type the term into the search tab and they get all the many matches they can find.

ClickHelp has a number of features specifically for such cases so that customers can always find the answer to their question:

-— A full-text search system in which readers can search the entire documentation portal or just a specific se t of user manuals. It handles word forms and tenses so readers can use natural language, and considers term proximity and other factors when ranking results.

— Index System. If you think a user will still have trouble finding some information in your documentation, ClickHelp's index or taxonomy system will solve that problem. This feature is designed to make topics searchable by terms that are not directly in their contents.
For example, if your documentation has a topic about SSL encryption, you can assign the index keyword "security" to it, and even if there is no mention of "security" or any derivatives in the topic, it will still be searchable by that term.

ClickHelp provides for teamwork. The service allows you to monitor the development process, leave comments, notify your colleagues per email and distribute roles.

Pros:
+ Ability to work in a team via a web interface and track results.
+ Documentation search.
+ Automatic translation of documentation into any languages.

Cons:
- Rather difficult to master the product and interface
- High cost of license.
- No ability to work offline.

4. HelpSmith

One of the main features of HelpSmith is the ability to create multiple help note formats from a single source. Thus, with a single source text, you can export it to HTML for creating web notes, to PDF, to MS Word, and to ePub format for e-books.

The program has a built-in image manipulation tool, somewhat reminiscent of Dr.Explain. It allows you to edit images and add annotations to them. In addition, all the media you use in your project is stored in a single repository, making it easy to update and save images to documentation.

For experienced technical writers, HelpSmith provides flexible conditional compilation options, allowing you to create different versions of the same help file for different user audiences.

A help file or web help system can be easily integrated into your application or website, so you can provide context-sensitive help by exporting a list of topics to a header file compatible with your IDE, such as C #, VB .NET, Delphi, C++, MS Office VBA.

Also, an unusual additional feature of HelpSmith is Syntax highlighting for creating API documentation, help files with code examples and any other kind of documentation containing program code written in different programming languages.

Pros:
+ large list of features that allow you to create a complete user manual of high quality
+ simplicity and ease of use.

Cons:
- Lack of a simple multi-user mechanism
- Lack of Mac and web versions

5. MarkdownPad

MarkdownPad is a well-known Markdown editor for Windows. It is as simple and easy to use as Microsoft Word and comes with a WYSIWYG editor, so you don't even need to know Markdown.

MarkdownPad is great for you if you need to quickly put documentation on a website, create a website, and anything HTML related. You can see what your documentation will look like at any time using the preview.

Everything is customizable. You can take advantage of extensive customization options such as layouts, fonts, and sizes. You can also include your own CSS style sheets. It comes with a CSS editor built in to the platform, so you can style the text to your liking.

Pros:
+ Very handy and overall simple program that we didn't even get to write more than 3 paragraphs about it
+ Cost.

Cons:
- Small functionality, compared to most similar tools.

Conclusion

User documentation is an indispensable tool that allows you to strengthen user loyalty, cover technical support, and increase the SEO-factors of the product.

Creating really high-quality documentation that will be useful is a hard task that will require a lot of time and effort. HAT (Help Authoring Tool) programs were created specifically to simplify this task, and we tried to give you a list of the best such tools.

See also

• How to write a user manual for software or a WEB service: tips, tricks and tools
• White Papers: Writing Cost-Effective Documentation for Software Systems
• Windows Software Help Files Formats