Writing Great Support Documentation

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.

Avoid Duplication

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

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.