Types of software documentation

Software documentation in general can involve very different kinds of documents. This often results in misunderstandings.


Types depending on the use of the software documentation



First, you can distinguish software documentation for internal use with the software manufacturer from software documentation for clients.


Important software documentation types for internal use include:

  internal project documentation

  source code documentation


Important software documentation types for external use―that is for clients―include:

  user documentation

  interface documentation (API documentation)


Types depending on the information type of the software documentation



Typically, user documentation includes at least three very different basic information types:

  basic information about the software’s underlying concepts; often also additional basic domain knowledge that readers are lacking

  procedures (task descriptions)

  reference information to look up, such as information on particular parameters


Usually, it doesn’t make sense to mix these information types because users typically don’t need them at the same time. For this reason, these information types are often even split into different documents, such as into a user manual and a reference manual.


Types depending on the medium of the software documentation


In addition to the content, we can also distunguish software documentation by its media:

  printed or printable manuals with a fixed order of pages (including PDF)

  online documentation (online help) as hypertext, usually HTML

Software documentation should be part of a global software user assistance solution



Software documentation for users should always be part of a larger context: the context of software user assistance. Software user assistance involves all measures that support users to accomplish their tasks. In addition to traditional documentation (user manuals and online help), global user assistance also includes in particular:

  small helpful texts within the user interface

  screencasts (YouTube videos)

  interactive tutorials

  sample projects

  user forums and communities
 

Requirements for software documentation

Basic requirements


The most important (but also the most often neglected) requirement for software documentation is: The software documentation must answer the users’ questions and it must enable the users to use the product completely and efficiently. Nothing else! It does not matter what we want to tell the readers. The only thing that matters is what the readers want to know. No matter how proud we are about a particular detail of our product, no matter what buzzwords the marketing department might like to hear: There is no place for useless stuff like this in software documentation.

The challenge of creating software documentation is to design the software documentation so that it exactly fills the gaps in between what the readers already know and what the readers don’t know but need to know. Less information is too few, more information is too much.

Don’t fool yourself: Nobody reads documentation for fun. Users only read technical documentation, including software documentation, if the pain of having to read the documentation is smaller than the pain of not being able to use a particular feature. So, writing good software documentation is all about eliminating pain.

The pain will be minimal if:

  the information can be found quickly without having to go a long way around

  exactly the needed information is found without having to ready any irrelevant stuff

  the information can easily be understood with as little mental work as possible

  the information can be applied directly to the readers’ own situations and problems

  reading takes as little time as possible


Legal and contractual requirements


Other than with other forms of technical documentation, for software documentation there aren’t many legal requirements and standards that you need to follow. In most cases, there is only the general requirement for technical documentation, which says that the documentation must enable clients to use the product successfully and completely.
In addition, there may be some special requirements resulting from contractual agreements with clients, or from things that are explicitly advertised. For example, if you advertise with the fact that your software comes with a particular interface, you also need to document this interface so that your clients will be able to use it.
If a piece of software controls a machine or another physical device, standards that apply to this device may also be relevant for the software documentation. In particular, this applies to requirements for the design of warnings.
 

Who creates software documentation?

Developer or technical writer?



Writing software documentation is not a task that developers typically are very keen on. Anyhow, much software documentation is written by developers. In addition to the lack of motivation, having developers write software documentation has one more major downside: The developers of a product are far too deeply involved into the details of the product to be able to explain the product to an outsider in an easily understandable way. In particular, this applies to user documentation. Only very few developers actually manage to take a step back and to design their software documentation in a fashion that reflects the mental models, the way of thinking, and the actual questions of the users.

Creating technical documentation, including software documentation, in a professional way needs some special expertise and talent. Today, you can study technical communication and technical
documentation at university and even after that it takes years to become an expert. It seems so easy because everybody can write. But not everybody can write so that everybody understands.

On the other hand, developers have the great advantage of working directly at the “
source of the information”. So, potentially, they can also cover subjects that other authors might overlook.


Conclusion


Developers always are indispensable suppliers of information. As a general rule, the closer some documentation needs to be to the code, the more likely the documentation should be written by a developer―such as API documentation, for example. The more some documentation needs to take care of the users’ needs, the more likely the documentation should NOT be written by a developer but by an experienced technical writer.

A very efficient way for creating software documentation can be a combined approach: Developers and subject matter experts collect the facts and write a first draft of the documentation without “wasting” time on style and perfection. In a second step, an experienced technical writer transforms this material into well-structured, clear software documentation that readers can easily understand. What makes this approach so efficient is the fact that everybody involved does exactly what he or she can do best.
 

Best practices for software documentation

If you want to produce professional, high-quality software documentation, you can’t expect a developer to come up with this documentation just like that in addition to his or her normal work.

If you can’t employ a technical writer and if you don’t want hire a qualified contractor specialized on creating software documentation, there is only one option: You need to enable the persons who will be responsible for writing the documentation to create clear, user-friendly documents themselves.

You can achive substantial improvements very quickly. Like in so many areas, the well-known 80-20 rule (Pareto principle) also applies to technical documentation: 80 percent of a possible increase in quality can be achieved with only about 20 percent of all possible means. The quality levels of documentation that has been written with and without following some basic best practices are miles apart!

The key areas are:
 
Best practices for structuring
software documentation

Which documents should you create? Printed or online or both? How should you organize these documents? How can you quickly guide the reader to just that piece of information that this particular reader needs?
 
Best practices for designing software documentation

How can you design your documents so that these documents don’t only look professional and appealing, but also so that readers can easily read, understand, and memorize the documents’ content?
 
Best practices for writing software documentation

How can you write clearly and simply so that readers can understand the information with as little effort as possible? What needs to be said is typically complex enough, so at least the language should be uncomplicated.

For example, my trainings and books teach you exactly these best practices in a concise form.
 

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, Helpinator

  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, Manula

  DITA-based tools
Tools based on a special, standardized XML structure that 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 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 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?

Additional tools


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, Automation Anywhere, 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
 

About Me and My Services

My name is Marc Achtelig. For more than 20 years my main occupation has been designing and writing software documentation.

As a software documentation consultant and freelance technical writer, I provide the following services:

  Improving existing documentation

  Designing new documentation

  Writing manuals and online help

  Creating document templates (style sheets) for manuals and online help

  Assistance in choosing authoring tools

  Trainings, workshops, mentoring


If you are interested, you can find more detailed information about my services on my main web site www.indoition.com.

If you have any questions, don’t hesitate to ask. You can find all contact details below.


Yours
Marc Achtelig
 
I am looking forward to hearing from you.

Marc Achtelig
Technical Communication Services

Goethestr. 24
90513 Zirndorf (near Nürnberg)
Germany

Email:  info@software-documentation.eu
Phone:  +49 (0)911/60046-659
Fax:  +49 (0)911/60046-863