I recently took a course on creating better documentation for software as part of my goals for this year. This article is going to focus on my key takeaways.

What is software documentation?

Software documentation is a form of (technical) communication. The documentation informs the user on what a particular software does, the features, and how to use them. It serves as a guide on using the software from the beginning e.g. installation to end. It can be in the form of texts, images, infographics, or a video. It can also be a combination of all the forms. The most important thing is that the user understands the product and can use it to achieve specific results.

Types of software documentation:

There are two types of software documentation:

• Functional documentation: This focuses on describing the user interface of the product. It highlights the different elements and what they do. For example, I have created this documentation of the web login page of Barter, an app by Flutterwave. It only describes what the user can see.

• Task-oriented documentation: This is usually the most sought-after type of documentation. The task-oriented documentation describes how to use the product. It guides the user to achieve specific results with the product. An example is this video showing how to log in to a Barter account.

Points to note when creating a documentation

• As the technical writer, you are an advocate for your end-users. Your focus is the user and their needs, not what your manager or other stakeholders want.

• The end-users read your documentation to solve problems. Create guides on how to get specific results with your product.

• Documentation does not have to be only text. Descriptive images and videos can help your readers to solve their problems faster.

• Quality software documentation should be helpful, comprehensive, accessible, searchable, visual, and reliable, amongst others. These qualities work together to deliver an excellent experience for your readers.

• Lastly, research is a critical part of the process. I will explain two categories:

  • What your readers seek: It will help if you can identify the specific problems your readers need to solve. A close example is this tweet from Youtuber, Ali Abdaal (big fan here). He attached a picture listing four potential topic ideas for his channel and asked his followers to select the one that would help them the most. Doing this ensures that his content is relevant to most of his followers.

  • Your content: After gathering information on your readers' needs, you also need to research how to solve those needs. You can do this by:

    • Reading related materials to gain more insight

    • Testing the product to confirm that it solves those needs.

These, and other research methods not listed, will help you create relevant content.

Summary

Technical documentation is a means of communicating parts of your product to your users. It can be functional, i.e. highlighting elements of the different screens and their functions. It can also be task-oriented, i.e. explaining how the product solves problems. Regardless of the category, it should be easy to understand and navigate. Clear and structured documentation will help your readers to achieve results with your product.