What are the principles of software documentation?

Overview

Software documentation is a document that contains information about software and how to use the software. This document is usable by both users and developers. In this shot, we discuss the steps in developing software documentation for any product.

Detailed overview

Here are guiding principles for developing software documentation:

1. Identify the audience: The target audience for documentation is significant. Is the documentation for the software developers? Is the documentation for software users? These questions should be kept in mind.
2. Identify the user's information needs: What medium would be most suitable for the target audience? Would a video guide on the use of the software be most appropriate? Would a graphic illustration be most acceptable? Would the documentation be better as a written document? We need to consider these questions, too.
3. Decide on a usable style guide: Software documentation is written based on the style guide. A company's style guide often correlates with the brand of the company. If there is not an existing company style guide, one can create a new style guide.
4. Decide the deliverable: A deliverable is the number of documentation pieces appropriate for the software. In the case of complex software, we would need a lot of documentation to help and guide users around the software. Do we translate the documentation to other languages? How many languages are there in total?
5. Decide the documentation tool to use: There are so many tools for software documentation. Having a custom tool helps keep track of a company's style guide. Examples of tools available are GitHub wiki, Darwin information typing Architecture (D.I.T.A), XML, and so on.
6. Decide the documentation structure: The technical team working with the developers decide the information architect of the software and can decide the amount of documentation possible from the software. This is used to structure the documentation.
7. Write the documentation: We write the documentation for the software.
8. Publish the first version of the documentation: We publish the first documentation version to gain feedback from users and developers. This will help for further development.
9. Collect feedback and improve the documentation: We receive feedback and work to improve the initially-released documentation.
10. Repeat the process: We repeat the process until it meets standards and expectations.

A usable software documentation manual is produced when this process is followed.