Writing technical documentation refers to written text or illustrations that accompany computer software or are embedded in the source code. It provides information on how to use a software program, explains the purpose of its various components, and gives an overview of the program’s capabilities.

We will explain in detail for various interest groups.

• How it works,
• Results and processes,
• Operation,
• Technical requirements,

and also differentiate according to the respective activities.

What types of software documentation are there?

There are many types of software documentation, ranging from system overviews to detailed specifications of individual components. A fundamental distinction is based on the intended audience: internal use or end users. Each scenario has different requirements.

Internal software documentation

This is a type of documentation created by the developers of a software application. Among other things, the following types of internal documentation exist:

• Developer documentation
• Data documentation
• API documentation
• Installation documentation
• Test documentation
• Project documents
• System documentation

The developer documentation is intended to help other programmers who need to work on the code in the future. This documentation can contain information about the application’s architecture, code structure, and the use of the software’s various functions. 

The data documentation is intended to help understand, classify, and work with the data required or generated by the product.

The installation documentation, on the other hand, describes, especially for more complex systems, how and in what order system components must be installed and set up to ensure overall functionality.

The test documentation attempts to describe the tests that are necessary to verify the correct functioning of the product.

Project documents are primarily intended for the planning and organization of software development, for example when it comes to planned objectives, tools used, or approaches. System documentation describes a more complex system, including all its components, functions, and how they interact.

External software documentation

External software documentation refers to documentation that is not part of a software program’s source code. This includes anything intended for people who are not among the software’s developers.

While external documentation can be very helpful in understanding how to use and configure a program, it can also be a source of confusion and frustration if it is not well-edited, clearly written, or logically structured.

Examples of external software documentation include:

• User documentation/user manual/user documentation (as PDF or printed)
• Online help/context-sensitive help
• Guides and tutorials
• Third-party API documentation

What requirements must be met for software documentation

General requirements

The requirements for software documentation do not differ significantly from the requirements for other types of documentation:

1. The questions of the end users are answered, enabling them to use the product correctly.
2. The documentation is easy to understand and concise.
3. It is tailored to the needs and tasks of the users.
4. Delivery usually takes place together with the software.
5. The documentation must also meet legal requirements.

Standards

There are various ways to create user information (user manual) for software solutions. This doesn’t mean creating it “by guesswork,” but rather that the approach and implementation should be based on current best practices, such as the state of the art.

Who writes software documentation?

Developer

Many developers create their own software documentation – to varying degrees. Those who programmed the software know exactly how it works. Unfortunately, this can also lead to explanations that far exceed the technical understanding of users. As a result, technical details may appear during the documentation process that are more confusing than helpful. After all, to use software, users usually don’t need to know the intricacies of its inner workings.

Professional users

Documentation can also be written by qualified subject matter experts. Since they work with the software regularly, they usually know what information other users need. However, such users are rather a matter of luck, and software developers should not rely on user information being generated in this way.

Technical writers

Trained members of a technical writing team specialize in providing software users with clear and easy-to-read instructions. Technical documentation writers typically familiarize themselves with the application and test its various functions. This allows them to automatically adopt the perspective of an inexperienced user and understand what kind of information is relevant to those reading the documentation.

What should be included in software documentation?

It typically contains a description of the software, instructions for its use, and all relevant information for developers or end users. Effective software documentation for end users should include information on the following aspects of the product lifecycle:

• Installation: How is the program installed on a computer and what are the requirements for this?
• Configuration: How must the software be configured to meet the user’s requirements?
• Usage: What possibilities does the product offer and how are they used?
• Troubleshooting: What errors can be expected and how can they be resolved?
• Customization options: What other options exist to extend the functionality of the software, e.g., through add-ons?
• Updates: Are updates expected and how frequently do they occur?
• Uninstallation: How can the program be safely removed from the system?

Especially with software that uses a graphical user interface (GUI), screenshots should be provided to help users navigate the software. Without them, finding your way around can quickly become confusing and frustrating. Make sure that the screenshots clearly show what the task is, for example, which button needs to be clicked.

What are best practices for software documentation?

There is no universally applicable answer to this question, as best practices for software documentation vary depending on the application being documented and the needs of the target audience. However, there are some general tips that can be followed when creating effective software documentation:

1. Simple and clear: The documentation should be easy to understand and free of technical terms that are unfamiliar to the target audience.
2. Be concise: Include only the most important information and leave out everything that is not directly related to using the software.
3. Use visuals: If possible, use images, screenshots or diagrams to supplement the text and explain complex concepts.
4. Logical structure: The information should be presented in a consistent and easily understandable structure.
5. Use consistent formatting: Ensure that the documentation uses a consistent format throughout, including headings, fonts, etc.
6. Include links: If appropriate, include links to external resources that can provide further information on a particular topic.

What are the most important things to consider when creating developer documentation?

Before you begin developing your software, you can simplify your work by starting to write the documentation simultaneously. Keep the following in mind:

1. Define the intended use of the developer documentation and/or the target audience for internal developers.
2. The scope of the developer documentation also depends on the target audience. Therefore, you need to consider in advance what information, resources, databases, and source code comments will be required.
3. Decide which content relevant to your case should be covered: program structure, functions and sub-functions, lists of program variables and used files.
4. Observe the documentation standards for the programming language, if any exist, as is the case with Java, Visual Basic, or C#. This can simplify working on developer documentation, especially when multiple people are editing it simultaneously.
5. For very long source code, you might consider creating an additional help file that references relevant keywords.

What are the most important things to consider when creating user documentation?

In addition to the best practices mentioned above, you should consider the following approach:

1. Determine what form your user documentation should take. From classic PDFs to online help: you have many options for presenting the information.
2. Think carefully about who your target audience is. You need to know whether they are tech-savvy specialists familiar with complex programs or occasional users.
3. Adapt the depth and complexity of the writing to this target group. Some processes need to be described in more detail for an inexperienced user group.
4. Please note the points mentioned above, which explain what belongs in software documentation. If these elements are present, they must also be described.
5. Additionally, you should write frequently occurring use cases as instructions that explain step by step what the user needs to do.

What tools are available for creating software documentation?

The optimal tools for creating documentation depend primarily on the type of software documentation you need to produce. Besides classics like Microsoft Word or Adobe FrameMaker, there are more specialized options. Below is a list of various tools available for documenting software:

Help authoring tools

A Help Authoring Tool (HAT) is software for creating online help and other informational documents, often printable documents (PDF manuals) of varying quality. These are primarily suitable for user documentation.

• MadCap Flare
• RoboHelp
• Help & Manual
• Help Studio
• HelpNDoc
• HelpSmith
• Doc-O-Matic Author
• Paligo
• ClickHelp
• Document360

DITA-based tools

DITA-based tools are tools that are based on the standardized XML structure DITA and are specifically designed for software documentation. They are very well suited for large documentation projects. However, they are generally too complex and expensive to use for smaller projects of fewer than a few hundred pages.

• DITA Open Toolkit
• <oxygen/> XML Editor
• DocBook
• XMLmind DITA Converter (ditac)

Content component management systems (CCMS)

These are either based on DITA or function using their own proprietary structures. They are primarily intended for very large documentation projects. For projects under a thousand pages, CCMS are very expensive. However, with a certain number of languages, it can be worthwhile even for smaller projects.

• Author-it
• easyDITA
• DITAToo
• XDocs DITA CCMS
• Vasont CMS
• Scheme ST4

Converter for existing manuals

It’s also possible to convert a manual created with Word or FrameMaker into HTML-based online help. If you need to create online help quickly, a converter might be helpful, at least for a first version. However, in the long run, you should aim for custom-designed online help. Converted documents essentially remain manuals that only superficially resemble online help.

• WebWorks ePublisher

Semi-automated documentation solutions for short, step-by-step instructions

You can also use semi-automated documentation solutions to create a working basis for your documentation. This works as follows: You perform actions in a software program, while the documentation program records the steps and automatically generates a series of screenshots. A draft of the documentation is then generated from this data. This is only recommended for quick instructions and small projects.

• SnagIt
• FlowShare
• ScreenSteps

Semi-automated documentation solutions for GUI references

These programs can automatically scan a program’s resources and generate help topics from them. The tool takes screenshots of the user interface (GUI) with accompanying labels. Additional information can then be added as needed.

Basic documentation can be created quickly in this way. This solution can be particularly useful when time is limited and costs are low. Unfortunately, these tools only generate incomplete, fragmented documentation that requires manual supplementation, especially regarding specific instructions.

(Partially) automated documentation solutions for API documentation

These tools scan the source code for comments and generate API documentation from them – usually as HTML. If the comments are regularly updated along with the API, it’s easy to create the latest version.

Many good, freely available open-source solutions exist. A disadvantage is that adding custom content can be difficult. Therefore, these tools are usually used in conjunction with other tools.

• Doc-O-Matic
• Slate
• Document! X
• Swagger
• sphinx
• ReadMe
• NelmioApiDocBundle