Software documentation, a strange new world?

Corresponding service: Software documentation

Digitalization is increasing the need for software documentation. This article provides an overview of the characteristics of software documentation and is geared toward beginners. We will try to give an answer to the question what good software documentation is and what technical authors need to know to create it.

What is software documentation? 

Think of software as a river. If the software only features some basic functions, the river flows calmly in its bed. The more dependencies, data, and features a software has, the broader and wilder the river becomes.

Now imagine a user standing on the left bank of the river. Anxiously does he look at the rushing water. He wants to cross to the other side, but he does not dare. If only there were a bridge! Technical communicators build these bridges. They write software documentation that forms the bridge between the knowledge that users have and the knowledge they require to use the software correctly and efficiently.

Without the metaphor and shorter: Software documentation explains to end users, administrators, and developers how software works and how to use it.

Types of software documentation

We differentiate between four types of documentation around software:

• User documentation. The classical user guide that is shipped with the software, nowadays mostly electronically.
• Developer documentation. This type of documentation is intended for software engineers. It describes interfaces, frameworks, SDKs, technical standards, and APIs. Developer documentation contains all information that software engineers need for their development tasks, such as programming an extension for a standard software. 
• System documentation. An operator’s guide for one or more IT systems. System documentation describes the installed server, available services, programs, and interfaces; and how they interact and exchange data.
• Internal project and process documentation. This type of documentation provides internal knowledge, e.g. on processes, requirements, test cases, and technical concepts of a software development project. The same requirements apply for both internal and external documentation.

This article focuses on user and developer documentation.

Which requirements apply for software documentation?

The requirements on software documentations are not much different from those applying to other types of technical documentation:

1. Software documentation answers the users’ questions and enables them to use the product correctly.
2. Software documentation is easy to understand and concise. To come back to our metaphor: We don’t build a winding or incomplete brigde. We build a bridge that leads directly to the other end of the river, without detours or bumps.
3. Software documentation is based on the needs and tasks of the users. Users do not want to read long introductions before they come to the relevant content. They quickly want to find the right information and understand it.
4. Software documentation is usually shipped or made available with the software.
5. Software documentation must fulfil legal requirements. Several standards and guidelines apply to software documentation. We will not discuss the requirements from these standards in depth in this article, but we recommend that you study them because they contain valuable knowledge that will help you write good software documentation. Here is a selection of applicable standards and guidelines:

• ISO/IEC 82079-1: „Preparation of information for use (instructions for use) of products“
• ISO/IEC 26514: „Requirements for designers and developers of user documentation“
• ISO IEC IEEE 26511: „Systems and software engineering — Requirements for managers of information for users of systems, software, and services“
• ISO IEC IEEE 26512: „Systems and software engineering — Requirements for acquirers and suppliers of information for users“
• ISO IEC IEEE 26513: „Systems and software engineering — Requirements for testers and reviewers of information for users“
• ISO IEC IEEE 26515: „Systems and software engineering — Developing information for users in an agile environment“
• ISO 15289: Systems and software engineering - Content of life-cycle information items (documentation)

Who writes software documentation?

Not only technical communicators write software documentation. Others do as well:

• Software engineers: Software engineers build bridges as well and write documentation. That can be an advantage because who knows the software better? On the other hand, this knowledge can turn into a disadvantage. Sometimes, it can be difficult for engineers to put themselves in the shoes of the users and reduce the amount of information to the exact knowledge that users require for a specific situation or task.
• Subject matter experts: Experts for specific domains or fields, such as logistics, also write documentation. They may already be involved in designing software or in the product management and thus know the software.
• Technical communicators: Trained technical writers are specialized in user-oriented writing. They test the software and get familiar with all features while writing the documentation. Technical communicators explore the software from a user’s point of view and find out which knowledge is required for which tasks.

Who do you write for? Know your audience!

We stated above that software documentation needs to answer the users’ questions. That is why you need to get to know the users and analyze your target audience. The analysis tells you the following:

• Who are the users?
• What do the users know?
• What do the users expect?
• Which tasks do the users perform?

Who are the users?

When we write software documentation, we often come across three typical target audiences:

• End users: They use the software for their daily work.
• Software engineers: They develop extensions, plug-ins, or use the product’s API.
• Administrators: They configure the software, are responsible for updates, rollout and maintenance.

Based on these target audiences, many software products come with the following information products:

• User guide
• Programmer’s guide
• Administrator guide

If you write for different target audiences, you need to analyze them separately. That means you have to answer the questions in the following sections for each of the audiences.

What do the users know?

First, you need to find out what the users know. Which knowledge do they have and which do they need in order to work with the software efficiently? For this purpose, we have developed a questionnaire. With the following example , we tried to find out which knowledge the users of an administrator guide have. For each answer, we can draw a conclusion for the design of the documentation.

 

Which expectations do the users have?

There are several areas of expectations. 

I've always done it this way!

You may come across users who have worked with a previous version of the software, for ten years or more. Then you could hear statements like these: „I’ve always done it this way!”, “Where is my PDF?”, “I do not need an online help!”.

Some users may have developed habits using former versions of software and documentation. These habits may shape expectations. But maybe you can make a deliberate choice to break with these old habits.

Layout and media

If and to what extent you use images, videos or other meda also largely depends on the expectations and knowledge of the target group:

• If users are more used to and oriented towards text, you can reduce the number of images in the documentation to a minimum.
• Administrators may not need screenshots if they only need the information about specific configuration parameters.
• An unskilled user may need stronger visual support for an unknown software, e.g. screenshots, video tutorials, screencasts, etc.

Access to online help

Usually we deliver software documentation as online help, webhelp or PDF. You will hardly find any printed software manuals any longer. Which delivery format you use, also depends on the expectations of the users. Perhaps users prefer PDF because they are used to working offline or want to print out individual pages or sections. Or your target audience is used to online help and does not need a PDF at all. If the target audience is used to PDF, you can deliver that format in addition to the online help. This way, you reach all users.

Information demand

By now you should know what the users know. Which means you have decided whether you need to explain domain-specific concepts or not. Next, you need to find out which knowledge the users require.

• You should always assume that the user has basic knowledge about software: Most people know how to close a window or open a menu. No need to explain that. 
• Standard tasks vs. special cases: One of our customers is a large logistics company in Hamburg. Their logistics experts know how to perform standard tasks, such as create an offer for a shipment to Shanghai, calculate freight rates and surcharges, monitor the freight, etc. They probably do not look up these tasks in the documentation.
  
  But what happens if the ship is rerouted to Singapore and surcharges change? The logistics experts may not have that case every day and do not know how to calculate the surcharges for Singapore in the software. That means that the documentation may need to contain more descriptions of special cases.

Which tasks do the users perform?

Software documentation, end user documentation in particular, is mainly task-oriented. For this reason, you need to identify the tasks that the users perform with the software. There are two possible ways to do that: You analyze (1) the product lifecycle of the software and (2) the tasks within the related business processes.

Product lifecycle

The lifecycle of a software consists of the following periods:

• Installation
• Configuration
• Operation
• Troubleshooting
• Customization 
• Update
• Maintenance
• Deinstallation

You can use these lifecycle periods as a basic chapter structure for your documentation. Even if you do not organize your documentation in chapters, you can derive documentation topics from lifecycle periods because documentation standards and guidelines require that specific lifecycle periods are covered.

Tasks within business processes

The second way is complementary. You can also determine the user tasks by analyzing the business processes covered by the software. Let us go back to our logistics company. Before we write a new chapter for the documentation, we analyze the associated business processes and identify tasks linked to the processes. Here are some tasks from the process of shipping a container to Shanghai.

1. Create an offer
2. Accept an order
3. Calculate freight rates and surcharges
4. Monitor a shipment
5. Deliver containers
6. Check incoming payments
7. Create the monthly statement

These tasks translate into topics for our documentation. When you look at the lifecycle periods again, you will note that steps 1-7 probably can be put into section “Operation”.

Who does what?

Now you know the tasks. Let us check who performs them. You can use a “Who-does-what matrix” for this purpose. Again, we take a look at the tasks in the process “Shipping a container from Hamburg to Shanghai”. There are four target audiences: operators, subcontractor, accountant, controller. For each target audience, there is a separate information product: Operator Manual, Subcontractor Manual, Accounting Manual, and Controlling Manual. In the table, mark the target audience for which the task and associated documentation topics are relevant.

The matrix helps you sort contents into information products.

If the tasks are clearly distinguishable and there is no overlap of information between the information products, you can create separate content, for example for Operator Manual and Controlling Manual.

However, several target audiences may perform a task together. For example, both operator and subcontractor monitor the container shipment. In this case, you have several possibilities:

a) You can decide to create only one set of topics and reuse the topics for different information products.

b) You can include content for different target groups in one information product and maybe cluster it accordingly within the information product.

How do users act?

Creating user-oriented documentation also requires us to understand how people use documentation. There are different types of users:

• The I-do-not-need-the-manual user
• The occasional reader
• The thourough learner

Be careful, however. Do not think within these boxes only, because the types never come as a 100% edition. Usually, several types are mixed. But the typing helps you anyway to identify the type of information required for the type of user.

I do not need the manual

These users immediately start to work with the software.They do not consult the documentation first. They will only look into the documentation when a problem occurs. If our logistics expert were of this type, she would only search the online help if the standard procedure is disturbed – maybe because the ship cannot dock in the port of Shanghai because of a storm and the load is cleared in Singapore instead. Freight rates and surcharges need to be changed. How does she do that in the software?

• Such users need help for solving problems. They read task topics, FAQs and troubleshooting topics. Most convenient for them are online helps or web portals, because then it only takes seconds to find the right answer. That means that your documentation requires good indexing and tagging and a full-text search.

The occasional reader

These users read documentation on demand, before they start working with the software. If needed, they read task topics, use cases and reference topics. If, for example, the administrator of the logistics software belongs to this type, she would press F1 to open the context-sensitive online help and find the description of the parameters she needs to configure.

• For these users you will need a context-sensitive help that describes the dialogs of your software.

The thorough learner

These users want to understand the general architecture of the software and how it works. They read introduction and concepts.

• For learners, you create concept topics, background information, and architecture diagrams.

Serve them all

There are users who only read tasks. Others prefer conceptual information – and once they have built up a mental model of the software, they do not read the tasks because they know their way around. That is why we recommend creating content for all user types because your target audience will have them all.

How do users access documentation?

Today, we read documentation on different devices: desktop computers, mobile phones, tablets, or in an augmented reality scenario with smart glasses. That means you need to generate different output formats for your documentation. If you use a structured format like XML or markdown, you can create format-neutral content and generate different output formats from it.

When and how do users read?

Another question that you need to answer is how and where users read the documentation. Do they read online or offline, for example?

Do you know this situation? You are on a speed train and work on your presentation. Then you need some help with Powerpoint. But there is no internet at 100 mph and the Microsoft help does not work offline. This may be acceptable for Microsoft products, but there are other types of software products that need to be available offline. Think of medical device documentation, which needs to be available offline because the devices must not be connected to the internet.

We have had good experience with web helps that can be used offline. Web helps include full-text search and index which guarantees that readers can search the help offline as well.

How do users search?

Another important question: How do users search the help? Do they want to talk to a chatbot? Do they prefer to type their question into a search field? Or are they work old-school and use the table of contents?

A usability test answers these question. Many companies skip these tests because they are not cheap. But in the long run, usability testing saves money, because the results will help you to make the product more user-friendly, reduce support costs and documentation load. Technical communicators can help with usability testing and act as testers themselves. This is especially useful for small companies that do not have a large budget to spend.

In the next part: topic-based authoring and tools for documentation and delivery.