Writing Great Support Documentation
Let’s explore some of the ingredients that go into creating and maintaining great support documentation.
Whether you’re just starting out generating content for your new knowledge base, or maintaining an existing one, understanding how to write effective articles leads to better user experiences
Get to the point!
When people are reading support documentation, they’re usually looking to solve some immediate problem they’re dealing with, so it’s important to make your documentation clean, clear and easy to find solutions.
This doesn’t mean that documentation needs to be minimal, or that you should skip details. It means that the detail should be there if readers want it, but it should be easy enough to skim over to find the specific section they’re interested in.
Once readers have located the section that relates to their current search or issue, then they may want to look in more detail. Especially when it relates to solving some problem or changing a setting. Images and examples can be especially effective when describing this level of detail.
Wherever possible, structure your documents in a way that makes it easy to quickly navigate to sections that describe distinctly different topics. You can always edit and rearrange the structure over time, however maintaining some organization at the 10,000-foot level will help your readers zero in on what they need to find. There’s nothing more frustrating for readers looking for help than needing to wade through lots of unnecessary walls of text.
It is often a great idea to create a quick summary or outline of what the article is about at the very top, allowing users to quickly decide whether to keep reading or move on to another article. These outlines should be very brief and to the point.
Use Short Article Names
Try to avoid using lengthy sentences as titles. For example, the title “How you can install and configure an HTTP web server using apache” could be simplified to “Apache Web Server Setup”.
Simpler titles will be easier for users to search, since superfluous words only confuse search engines, and ultimately users will know what they are looking for, so they will likely search for that.
Also, using lengthy names can become tedious when you’re looking through a list of topics if each one is a full sentence. Skimming through brief titles will get you to where you want to be more efficiently.
Focus on action when choosing an article title whenever possible, as you write support documentation, so things like
“How to XXX…”
“Setting up XXX…”
or “Troubleshooting XXX…”
would be good examples, since these are short, to the point and meaningful when users see them. You can also use meaningful verbs, such as “Uploading Images”, or “Downloading Reports” for example. Titles that fully describe what the article is about are most helpful.
There are no hard rules on this, but as a general guide, naming articles effectively will pay off for your readers..
Your team should remain focused and productive, using their limited resources effectively.
This means avoiding duplication, whether that is in automating tasks or maintaining up-to-date copies of documentation.
If you discover that your team maintains multiple locations for storing the same information, this creates the likelihood that the content will diverge at some point, whether accidentally, or through apathy.
It is easier to keep a single source of truth for documentation. This is part of effective knowledge management, whose goal is to promote improved performance, innovation and continuous improvement of an organization.
Merge or split text as appropriate to reduce or remove duplication whenever possible.
It is often worthwhile to occasionally spend some time reviewing your product, marketing and support documentation to see whether you have any unnecessary duplication
The concept of “evergreen” or “dynamic” documentation has been around for some time, especially in this digital age, where a single version of documentation is always current. It grows and evolves to remain up-to-date as needed.
Prior to the emergence of knowledge bases and knowledge management tools, organizations would often create versions of documentation for specific product releases. Often these would be published as downloadable documents or pdfs. The main problem with this is that as soon as these were downloaded, they were effectively out of date, since products change continually and getting updates to those downloaded documents was no longer possible.
A better approach is to maintain a single version of documentation, which can be updated as frequently as needed to remain evergreen. This also means that the writers and content editors need to take into consideration users with different versions of the product or some features that may not be applicable to them. This clarification should be called out within the text itself, making it clear which versions certain segments of documentation relate to, assuming they are version specific.
By maintaining a single version, or single source of truth, you reduce the burden of having to maintain multiple versions of the same document, while making maintenance simpler. There are certainly occasions when it makes sense to create a completely new document when wholesale changes are made to a product, perhaps when introducing a new major release that is drastically different than is predecessor. In these cases, the choice to create a new document would likely become more obvious (since you may need to rewrite most of the prior documentation), but this too offers the opportunity to easily create reference links between the two documents, enhancing both.
Alternatively, if certain features warrant their own documentation, then creating articles specific to those features is preferable. Those articles can easily be references from other documentation, along with simple indicators of relevance to the reader.
“Keep it simple, stupid”
We’re sure you’ve all heard the old KISS acronym from the Navy. The same philosophy applies to documentation.
Certainly, there are times when documentation needs to become detailed and complex to convey messages, but many times, documentation, especially support documentation, is meant to be easily digested.
Try to avoid using overly technical terms or acronyms that your readers may not fully understand. If you do need to use them, be sure to call them out with an explanation or a reference link the first time they’re mentioned. Assume your reader has only a partial idea of what you’re writing about.
Feel free to browse our online documentation
Who are GoGoWorx?
Our goal is to provide you with effortless knowledge base management software in a fully hosted environment to help you create, publish and organize with ease
Want to learn more?
See some of our features and learn how easy it is to create your own online knowledge base in minutes
Ready to get started?
Learn more, or create an account