Wait a second, what is software documentation?
The term software documentation is intimidating to many. Even though it seems self-explanatory (okay, it consists of documents that talk about software), what does that mean exactly?
Well, software documentation is an umbrella term that encompasses a wide variety of different documents, so there's no catch-all definition. However, they're all united by one common goal. They provide information about software. To what end, you might be wondering?
Software documentation provides people with information so that they can effectively use or work on a piece of software. Some documentation helps end-users get oriented, troubleshoot or start using a piece of software. Other documentation provides programmers, developers, software engineers and other industry professionals with more in-depth technical information about a piece of software.
Whatever the case may be, great software documentation should clearly communicate information about a piece of software. People should always finish reading software documentation and take away new knowledge, capabilities or data relating to that piece of software.
Software documentation can be separated into two broad categories: user-focused and developer-focused. Keep reading, because we'll be discussing those documentation types in a little more detail later on.
Who uses software documentation?
The people who use software documentation are as diverse as the kinds of documentation themselves. In fact, there's truly something for everyone when it comes to the different types of documentation. Many people see the words software documentation and automatically assume that they're technical documents that are only used by developers. In reality, this is not always the case.
As we'll discuss in the next section, software documentation can be divided into different categories.
Some kinds of documentation are user-focused, meaning that they're normally read by end-users. This can include anything from customers to testers to external stakeholders.
Other kinds of documentation are developer-focused. These are normally the more technical documents that are assembled and referred back to by developers, programmers, software engineers, project managers and the like.
Of course, these categories are not set in stone. There are also kinds of documentation that are used by end-users and developers alike, as well as more specific sub-categories.
User-focused software documentation
First things first, let's talk about user-focused documentation. By now you've probably figured out that these kinds of documents are intended for customers and other users that are receiving the finished version of your software product. The goal of this kind of documentation is to help people use your software itself and/or features of your software. It can also provide them with details about your software, teach them how to download it and/or set it up and troubleshoot any issues.
This list is by no means extensive, but some common examples of user-focused software documentation include:
- How-to and user guides
- Release notes
- Reference documents
- Software design documents
- Explanations (often including videos, graphics & screenshots)
- Set-up and troubleshooting manuals
- Frequently asked questions
Developer-focused software documentation
On the other hand, we've got developer-focused software documentation. These documents are normally more technical and are used by people who are a part of developing a software product, or otherwise working on it after the fact. These people include programmers, developers, software engineers, project managers and other stakeholders.
Developer-focused documents are usually more difficult for people without industry experience to understand, but they should still be written as clearly as possible.
A variety of documents can fall under the umbrella of developer-focused software documentation, but here are some common examples:
- Back-end release notes
- Test plans
- API documentation
- README files
- Software requirements documents
- System documentation
- Source code documentation
- Other technical documentation & technical specifications