Good software documentation is incredibly versatile.
It caters to the needs of software users with different technical backgrounds and utilizes a whole range of features and resources to provide explanations, support, and assistance to those who need it.
In this article, we’re bringing you our list of features and practices that make good software documentation stand out.
Let’s dive right in and find out what makes good software documentation tick.
Good Software Documentation is Up to Date
Providing outdated documentation is a great way to waste a user’s time because they might not realize from the start that they’re using documentation that’s no longer valid.
Frustration is sure to set in eventually and in the worst-case scenario, the user might voice their anger on social media and churn from your service completely.
Have a look at how quickly a loyal customer can change their mind when faced with outdated documentation in the example below:
In fact, we could argue that outdated documentation is actually worse than no documentation because it can cause greater damage to your reputation and cost more to fix.
Users trust you to deliver accurate documentation.
Therefore, if just one bit of information is outdated, that trust is jeopardized because the reader doesn’t know if they can rely on anything else in the documents.
To make matters worse, an error in documentation will be seen as an error in the product itself, and users will come to view your product as low-quality because your documentation isn’t up to par.
All of this can be avoided if you put in the effort to keep your documentation fresh and verified.
See if your documentation platform has a way of alerting you when a document hasn’t been updated for a while.
For example, Archbee has a document verification feature that notifies a selected stakeholder that a document needs to be verified as accurate and up to date.
Source: Archbee YouTube
Allowing a couple of documents to become outdated can seem like a small problem to fuss over.
However, this issue can snowball pretty quickly and put off customers from your great product, so keeping documentation up to date is definitely a good practice to follow.
Good Documentation Has Great Product Descriptions
It’s important to understand that your existing customers aren’t the only people checking out your software documentation.
Potential buyers are also looking at your articles and trying to determine if your product is a good fit for their needs.
This means that software documentation isn’t only valuable for customer support and success. It has other business benefits, such as supporting your marketing and sales efforts. Here's a blog post about best practices in writing software documentation.
As a matter of fact, modern software buyers respond more to quality online content than traditional ads to make purchasing decisions.
To make your documentation representative of the value your product can bring to the lives of potential buyers, you need to do a good job describing it.
That’s why all good software documentation starts with a well-worded, but concise product description.
Let’s have a look at a good example.
This description does a very good job presenting the product. It contains a short definition of the software and explains how it can help potential users.
Finally, it mentions what results the user can expect once they integrate Breadwinner into their work.
Here’s another good example from Bokeh:
Once again, the description tells us what the product is, what its primary uses are, and how it can improve the user's work.
A product description is one of the simplest things you can do to boost product awareness and signal to potential customers that your software is exactly what they’ve been looking for.
There’s no need to be too creative or write at length. Just follow the examples we’ve outlined above and include the following:
- Definition of the product or service
- A summary of the tasks that can be completed using it
- The potential benefits that can be gained by using the product or service
Remember, software documentation can serve a lot of purposes, including attracting new users.
Don’t pass up on good opportunities and always include a product description in your software documentation.
Good Software Documentation Anticipates Failures
A peculiarity of software documentation is that it’s never read in a linear way, as you would a book. Instead, users consult specific articles at different stages of their journey with the product.
They access documents that deal with particular features or find instructions when they need to complete a specific task.
Perhaps more than anything else, users consult software documentation once they encounter a problem.
Today, software documentation has become the preferred user support channel, beating out even phone, chat and email support as people increasingly show a penchant for solving their own problems.
Following this logic, the smart way to write software documentation isn’t to focus on product features, but rather the user journey, including the issues users may face while they’re using the product.
The more issues or problems or failures you can anticipate, document, and provide solutions for, the more useful your documentation will be to customers who turn to it looking for answers.
You can do that by documenting issues that arise while you’re testing the software, as well as by incorporating customer feedback and customer support tickets in your documentation.
Once you have a solid database of potential failures your users might face, you can dedicate a section of your knowledge base to those problems (and the accompanying solutions).
That part of the documentation can take the form of a FAQ section, where questions about the product are asked and answered. Here’s what that might look like:
Another great format is a troubleshooting guide where issues are presented and then possible solutions are given so that the user knows what to check and how to start resolving the problem.
Last but not least, don’t forget that even developers can experience failure when working with your product, so it’s definitely a good idea to include resources for them as well.
For example, a section on error codes that the software may return with possible explanations and fixes.
The only wrong move to make here is to deny that users can experience difficulties with your software and fail to offer resources for them to fix their own problems.
So if you want to create good software documentation, anticipate failure and provide ways of overcoming it.
Good Software Documentation Has Examples
The better you can supplement your documentation with live code in the form of code examples and use cases, the more useful your documentation will be for developers implementing the software.
Here’s an illustrative Tweet that should help us prove our point:
This is a pretty standard opinion in the software development community. It’s even echoed by top technical writers who understand what developers need to complete their work.
For instance, Google’s course on technical writing starts with the same premise:
There are essentially two types of examples you can integrate into your software documentation:
- Code samples
- Code snippets
Code samples have a more illustrative nature. Their purpose is to show, rather than tell, the user how a particular system or feature was built.
It’s a way for documentation to speak to the developer in the language they understand and provide context on the architecture behind the software.
With quality code samples, developers have an easier task figuring out how a software product or API can be integrated into their own systems and work smoothly.
Once again, Stripe’s documentation is one of the best examples in this space and is often lauded for its consistent and immaculate use of code samples.
Here’s Stripe’s code sample for a checkout page:
In this code sample, the full code for the feature is given as an illustration of what the software can do.
On the other hand, when just a couple of lines of code are presented to describe an action or functionality, that’s usually a code snippet.
Code snippets are code examples that show the user how to complete a very specific task. Their main characteristic is that they can be easily copied and pasted to instantly take an action.
Here’s one from Github:
Here, a simple curl command returns a simple result (one of Github’s design philosophies).
Code snippets like this one enable developers to work faster by allowing them to take pre-written actions that they don’t need to code themselves.
They’re also a great educational tool because they let developers immerse themselves into the code and start playing with it from their first contact with the product.
Code examples are, therefore, your most powerful tool for explaining your software to programmers and helping them implement it quickly and smoothly.
Proving as many examples as you can is a great way to ensure effective acquisition and long-term retention.
Good Software Documentation Defines Specific Terms
Good software documentation should be self-contained, meaning users don’t need to consult other resources or ask for external help to understand the concepts within.
Like in this example from Reddit:
If the documentation doesn’t do a good job explaining its terminology and principles, sooner or later users are going to get stuck and won’t be able to continue working with the software.
To prevent that from happening, remember that it’s better to overexplain and offer ample resources defining your concepts, terminology, and processes, than to rely on users to figure everything out on their own.
Companies have different ways of approaching this problem.
For example, Zapier’s customer resources begin with an explanation of the key terms users will be encountering in their journey with Zapier’s software:
Specific terms like Trigger, Action, and Zap are outlined and then explained in simple terms so that the user never needs to wonder what’s happening or how the software works.
Providing key explanations and definitions is important on every level of software usage.
That includes basic concepts (like in Zapier’s example), as well as advanced terminology used by specialists such as programmers implementing the product.
That’s why good software documentation includes glossaries and references that provide explanations in one place, so that the user can quickly look up what they don’t understand and get back to work without becoming stuck.
Here’s an example of such a glossary. This one, from Zendesk, explains the terms a user might encounter while using Zendesk’s REST API:
Bear in mind that just one unclear term or unexplained concept can bring work with your software to a screeching halt.
You don’t want your users to become frustrated, so provide explanations for every specific term you determine might cause trouble for your users.
Good Documentation Has Detailed API reference
Speaking of references, there’s one more key element that makes good documentation software: a detailed API reference.
In fact, this resource is so important for programmers that many can’t imagine software working without it.
It’s easy to see why programmers feel this way. API references explain in detail each function, class, return type, and argument that make up the API.
These references also often include code examples (remember them from two sections ago?) and tutorials that show the user how to take an action with the API.
In fewer words, an API reference is a complete resource that enables users to work with an API and use it to its full potential.
Clearly, they’re not to be glossed over when software documentation is being created.
Spotify’s Web API is a good case in point.
As you can see, the capabilities of the API are neatly sorted into categories on the left-hand side.
Each category is then further divided into the singular endpoints or actions the user can take.
By clicking on the endpoint, the user is taken to the next page where the reference provides information on how to form the request and what responses they can expect.
There’s even a sample response shown on the right-hand side.
As we said, everything a programmer needs to work with the API in one place.
Developers will tell you that this is the most useful part of any software documentation, which is why we’re including it in our list of good documentation features.
Good Software Documentation Is Portable
Not too long ago, software documentation was a downloadable pdf file or even a printed book that contained everything a user needed to know about the software.
The problems with these formats should be fairly obvious. Documentation was easily lost, wasn’t accessible at all times, and was extremely difficult to update.
Thankfully, modern times bring modern solutions.
Software documentation providers now present their resources using dedicated documentation websites, making documentation portable and accessible at any time and from anywhere.
These websites are built using specialized documentation platforms that allow users to write, edit, publish, and maintain entire knowledge bases dedicated to their products.
Our own platform, Archbee, was developed with the needs of companies creating software documentation in mind.
Archbee has an integrated code editor, meaning document creators can input code in multiple languages as easily as they write explanations in plain text.
In addition to that, the feature that sets Archbee apart from other documentation software is its API integration capabilities.
Users can import entire API references or insert a single API endpoint with all its elements, which makes documenting APIs easier for developers and technical writers easier than ever.
The key takeaway here is that modern software documentation needs to be portable and accessible at all times.
The only way to do that is to choose documentation software that will allow you to present your documentation in the form of a dedicated website.
And if you’re working with software documentation, we recommend trying out Archbee as it has everything you need to create good software documentation.
Conclusion
As we’ve shown you in this article, there are many pitfalls that can make your software documentation sub-optimal and difficult to use.
Luckily, each one of these perils has a solution and our list of good documentation practices should help you avoid almost all of them.
Try integrating some of the features we outlined here and you’re sure to keep end users, as well as developers, happy and in love with your software.
