Inthis post, I’ll share tips that I use to organize my documentation which you implement in your documentation creating.

I use ClickHelp for technical writing — if you use a help authoring tool, too, the below features can be available, so you can use the tips, as well.

Arrange Topics in TOC

The best way to ease navigation in your long documentation is to create a TOC. It’s usually organized in a tree-like structure:

There are three types of TOC nodes:

• Topic nodes without children. It’s just a topic with information.

• Folders. They don’t contain information, just group topics.

• Topic nodes with children. In comparison with folders, such a kind of topics contains information and organize child topics.

A TOC helps users to find necessary information quickly. So, don’t just put topics as you wish — think over the structure of your document, create nodes of different types to group topics.

Navigation Inside Documentation

If your doc has a large number of topics, it’s a good idea to add navigation elements like:

• See Also List
• Top, Next, Previous Topic
• Mini-TOC
• Sidebar
• Automatic Navigation Element Title

I described some navigation elements and how they look in documentation here. Now I want to pay attention to a sidebar. Here is how it looks:

All related articles are in touch, so readers can easily find what they need.

You can add any information that you find necessary. For example, videos, pictures and so on:

Content Design

The content design is, probably, the most important part of writing and organizing documentation. This topic is large and, of course, I will not cover it here but I’ll describe some points and aspects that I usually follow.

Information, warning, and expandable box

I always highlight some important points to make it vivid. Here are examples of information and warning boxes.

Here is an expandable box that hides content, it keeps topic concise.

Code highlighting

Some topics may have code samples. In order to highlight them and make obvious, I use code highlighting.

Image preview

It’s not a good idea to add large screenshots that users have to scroll down. To make your screenshots comfortable, make it clickable to show up in a larger size. To do this, I use the Lightense library. You can read more information here: Image Preview — Lightense.

What are your tips on organizing documentation?