Tips for Writing Technical Documents (Part 2)

There are a few other things you can do to make a technical document helpful to users.

1. Use screen shots.

When writing instruction documents, try to avoid writing paragraph after paragraph of text-only instructions. Long sections of text can get hard to follow and tedious.

Instead, break up step-by-step instructions by including screen shots. Screen shots can help the user to stay oriented in the process and show the user exactly what they need to be doing.

Along with screen shots, you can also use charts and boxes that include tricks or best practices or insights into the workings of the system, all of which can help users understand processes.

2. Create a table of contents.

If a document is any longer than several pages, a table of contents is very helpful.

There will be times when a user is brand new to a system and will find it beneficial to read through a how-to manual from beginning to end. More often, though, users will need only a section or two so they can quickly accomplish a task. In those cases, they can use a clickable table of contents to go directly to the section they need.

By using headings consistently in Microsoft Word, a table of contents is amazingly easy to create, and your users will thank you for it.

3. Consider an index.

Similar to a table of contents, an index may be a useful tool for documents that are long. It’s another useful tool so that users can find what they need as quickly as possible.