How to Organize Your Technical Documentation

What’s one of the most important things in a user manual? Its structure! Usability largely depends on how well a technical document is structured. There are certain basic elements that bring logic to your docs.

We are going to talk about the best practices of their usage, so, keep reading.

TOC

A table of contents can be found in a lot of types of technical documentation. It includes nodes corresponding to each help topic title.

A TOC is the backbone of your technical documentation and it is a major navigation option for readers. Which means that TOCs deserve special attention.

In flexible software documentation tools like ClickHelp, a TOC can be modified at any stage of working on a documentation project by simply dragging the nodes. But moving TOC around is supposed to be your backup plan, never plan A, try to remember that. Planning out the main nodes in a TOC in advance is extremely important for future user manual updates.

Before actually creating a TOC, draw up a scheme and think about how the product features are going to be falling into place with the main nodes you’ve got at the moment.

Indenting is what helps your table of contents to make sense for readers. Please be mindful not to leave too much indentation without a strong reason (like a very complex project, for example). With too many levels, a TOC becomes unreadable and loses its main function – providing easy navigation within a user manual.

In ClickHelp, you can design TOCs to your liking by changing node icons. This has nothing to do with structure, but it is a nice touch for mimicking your corporate style. Branding user manuals is an important aspect of help authoring in modern technical writing.

More low-level structuring can be achieved with a mini-TOC. ClickHelp creates those automatically, with one click. A mini-TOC is compiled from headings of different levels that the topic features.

When you generate a mini-TOC, you can kind of overview the topic once again and make sure its structure is logical and not overly complicated.

Using Index

The Index is where people go to quickly sort help topics out and find the right one. It is an alternative to a search field and a new way to look at structuring your technical documentation.

In ClickHelp, there’s a really neat feature – you can add keywords the topic in question doesn’t actually have and the topic will show up in the search results when someone looks them up. This functionality allows fine-tuning search results to make them more relevant as, sometimes, people can be unknowingly looking up obsolete terms for certain things and get frustrated by not receiving relevant results.

Conclusion

Structuring technical documentation is tough. Some documentation projects include hundreds and even thousands of help topics. Using the TOC and Index functionality brings more clarity to the process of creating logically correct documents, which, in its turn, improves usability and simplifies further documentation maintenance.

Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices