Tools for creating software documentation
What are the best tools for creating software documentation mainly depends on which type of software documentation you want to produce. Roughly, you can break down software documentation tools into the following groups:
▶ Standard help authoring tools
Create generic online help plus often also printable documents (PDF manuals) of different quality. Typically best suited for creating user documentation. Examples: Flare, RoboHelp, Help & Manual, HelpNDoc
▶ Web-based help authoring tools
Provide essentially the same functions as the standard help authoring tools only that web-based help authoring tools can be used in your browser no matter which operating system you are using. Also web-based help authoring tools don’t need to be installed on each author’s computer. Have the typical advantages and disadvantages of web applications. Examples: HelpConsole, ClickHelp
▶ DITA-based tools
Tools based on the standardized XML structure DITA, which has been designed especially for software documentation. Powerful for large documentation projects. Mostly too complex and too time-consuming for smaller projects consisting of less than several hundred pages. Examples: <oxygen/> xml Editor, DITA Open Toolkit
▶ Content component management systems (CCMS)
Either DITA-based or with proprietary structures. Powerful for very large documentation projects. Too expensive for projects that involve less than several thousand pages. Examples: easyDITA, DITAToo, Author-It, Vasont CMS, Schema ST4
▶ Converters for existing manuals
Transform a manual that has been written in Word or FrameMaker into HTML-based online help. Can be a cost-saving solution for quickly creating an initial version of online help. Not very efficient in the long run. Also has the risk that the documentation will effectively always remain a printed manual even if it looks like online help at first glance. Examples: WebWorks ePublisher, WebHelp Authoring Suite
▶ Partly automated documentation tools for short step-by-step task descriptions
Automatically create a series of screen captures while you are performing a task within the software. Based on these screen captures and on what you did in the software, the tool then automatically creates a first version of your documentation. Not suitable for producing comprehensive documentation, but a quick solution for small task descriptions and for support purposes. Examples: StepShot, ScreenSteps
▶ Partly automated documentation tools for user interface descriptions
Automatically scan the resource files of a program and create help topics with labeled screen captures of each dialog. You can add additional information manually. The tools can quickly generate some minimal documentation if you have very little time or a tight budget. However, documentation generated this way almost always lacks crucial information. In particular, it does not provide any task descriptions. Example: Dr. Explain
▶ Partly automated documentation tools for API documentation
Scan the source code for comments and create some API documentation based on the source code plus the comments―typically online documentation in HTML format. The key advantage of this approach is that you can immediately create up-to-date documentation when you publish a new release of the software with minimum effort. In contrast to the other tool groups, you can find many good open source solutions here. The main disadvantage of these solutions, however, is that it is typically very hard or even impossible to add any additional content. For this reason, automated API documentation tools are often used in combination with standard help authoring tools. Examples: Doc-O-Matic, Document! X, Sphinx, Slate, Javadoc, ROBOdoc, Doxygen
▶ Self-made tools
Quite a few companies develop their own solution for publishing their software documentation. However, only very rarely these solutions are economical in the long run. Many years of development time have been invested into today’s commercial help authoring tools. You just can’t do a similar thing alongside your usual work. Even if some of the tools’ functions look quite trivial at the beginning: finally you will end up missing important features that make such a system truly productive. Then, when you look at the time that you lose, a self-made tool becomes very expensive! Another frequent problem with self-made tools is that the persons who have developed the tool one day leave the company, taking the corresponding know-how with them. Finally, the self-made tool slowly dies until after years of standstill a commercial tool is licensed …
By the way: Did you notice that Word is not among the listed tools? Even though a large proportion of software documentation is still written in Word, Word rarely is the best tool for this task.
You can find a very comprehensive overview of almost all available tools for creating software documentation in the Tool and Web Guide on www.indoition.com. In addition, I also provide workshops as a service where we can analyze your specific requirements and then pick out the tools that meet these requirements as best as possible. I can advise you completely neutral and free of any motives in selling a particular tool.
Single source publishing
Many tools for creating software documentation support what’s called single source publishing. Single source publishing means the ability to generate multiple documents from the same shared text base or “single source”. On the one hand, this can involve different media, such as a printable manual (PDF) and online help. On the other hand, it can involve multiple variants of the documentation, such as documentation for the Standard Version and documentation for the Professional Version of the same software. So, in this example, you would end up with 4 documents created from the single source: printed or PDF manual for the Standard Version, online help for the Standard Version, printed or PDF manual for the Professional Version, online help for the Professional Version. In real life, the number of documents is often much larger.
When creating the first version of a software documentation, single source publishing does not yet make any big difference. You could also copy and paste the text for each document. However, keep in mind that software documentation typically needs to be updated when the software grows. Now, when you have copied the texts. you need to make each update in various places. When you use single source publishing, however, you only need to edit one single source. Your changes to the single source will be automatically taken over for each document when you generate it. With larger projects, this can save days or even weeks of tedious work.
Important tool requirements
When you listen to what the manufacturers of the help authoring tools claim, each tool seems to be universal and superior. Of course, this is nonsense. No tool can fit all purposes equally. Telling which tool is the best one in your particular case needs some individual analysis and balancing of the corresponding pros and cons. When doing so, always bear in mind the following:
▶ Formats and quality: Which formats must the tool be able to create? How high are your requirements regarding the quality of the design of the output? Can you achieve this quality level with the chosen tool at reasonable costs?
▶ Special features: Do you need any particular functions for presenting the content or for providing navigation within the documents? Can you implement these functions with the chosen tool? Can you make generated online help systems context sensitive?
▶ Quantity: Can the tool manage and process the quantity of content that you are going to produce efficiently and reliably?
▶ Variants: How many variants of your documentation will you need to create in the foreseeable future? How much content will these variants share and how small or big will the differences between the variants be? Does the tool provide good single source publishing capabilities for this particular scenario? (Note that the tools have some major differences here that aren’t always obvious!)
▶ Frequency of changes: How often will you need to update your documents? How much work does it take to generate a new version of all documents? How much of the layout and publishing process can be automated? Can you integrate the production of the documents into the build process of your software?
▶ Languages: Does the tool support all languages in which you need to publish your documents? If applicable, does it also support Asian languages and languages that are written from right to left? Can texts be exported for translations so that translators don’t need to work in the authoring tool? Can translators use a translation memory system so that when updating an existing translation they only need to translate the changes but not everything all over again?
▶ Authors: Do the authors who need to use the tool feel comfortable with it? Or might they be reluctant using it? Is the tool simple enough to use even for persons who only contribute to the documentation occasionally? Can several persons work on the same documentation at the same time?
▶ Processes: Does the tool integrate with your internal development processes? Does the tool support documentation reviews? Does the tool provide version control? Do the operating system and the architecture of the tool comply with your organization’s requirements?
▶ Protection: Do you need to implement some form of access control for authors or for readers? Can you do so with the chosen tool?
▶ Legacy content: Do you need to migrate content from a prior system to the new authoring tool? Is it profitable to set up some automatic conversion? If so, how easily and how well can you implement such an automatic conversion?
In addition to the help authoring tools, there are various additional tools that can dramatically simplify and speed up your writing process:
▶ A good screen capture tool does not only take screen captures. It also lets you edit screen captures much more efficiently than you can do with some standard image processor. Examples: SnagIt, FullShot, MadCap Capture, H@rdcopy, SnapDraw, Greenshot
▶ A macro utility can automate repetitive tasks and it can help you to enter frequently used words and phrases. Examples: AutoHotkey, AutoIt, WinAutomation, PhraseExpress
▶ A good search and replace tool can automatically postprocess the output of a help authoring tool to add features that your help authoring tool itself doesn’t support. Examples: Text Workbench, TextPipe, PowerGREP, TextCrawler
▶ Style guides and dictionaries help you to write correct and consistent texts. Examples: Technical Writers’ Companion, WordWeb, Babylon
▶ In case you are going to translate your texts: A translation memory system (TMS, CAT tool) simplifies the translation process. Not only can you translate the texts very comfortably. If part of a text has already been translated before, the system even adds the existing translation automatically. Examples: SDL Trados, Transit, MadCap Lingo