Sharp Words

There are several ways of presenting information in technical documents - this article covers what I consider to be some of the main types. For convenience, I’m going to use the term product to describe what a document is about, and the term topic to mean a small, discreet part of a document that starts with a heading of some sort.

Overviews
An overview or introduction is a high-level description of the product or part of its functionality. You might start the guide with an Overview or Introduction chapter, which describes the key concepts of the product such as what it’s used for. The overview would introduce any essential terminology or outline how the product fits into a larger group of products (product suite).

The start of each chapter of a guide should also ideally have an overview section, which describes the focus of the chapter - for example, a chapter on Working with Word Documents might explain the concept of a document and then list some of Word’s functions for manipulating documents. The overview section can also outline the information given in that chapter, perhaps giving links to the different sections.

Informational topics
Aren’t these the same as overviews or introductions?  Well, no. An overview is just that - high-level information or a summary of other information.  An informational topic contains details specific only to that one bit of functionality - for example, in the Working with Word Documents chapter, you might have a topic titled Saving Documents.

Informational topics can contain subtopics too - Saving Documents might have sections on Saving Existing Documents and Saving New Documents. Each of these subtopics has information particular just to that subject matter.

Procedures
Another type of topic is a procedure - a how to - which is often a subtopic of an informational topic.  For example, Saving Existing Documents might have a procedure called To save an open document. These are probably the meat and drink of a technical writer’s work, particularly for user and administration guide. Unless you explain to the readers how to do something, the rest of the information in the guide isn’t necessarily much use.

A procedure would usually have some sort of introduction (often in the informational topic that precedes it) to explain why a user might want to follow the procedure, and what requirements there might be for it.  I’m going to talk about writing procedures in depth in a later article though.

Reference topics
Again, these aren’t the same as informational topics although they have a lot in common. Reference topics might include, for example, a list of the options on a dialog box or the buttons on a video recorder. Information in these topics is generally presented without context - it’s what something does, not why or how it might be used.

Example structure of topics
So, for a chapter named Working with Word Documents, a sample section of the table of contents might be:

Chapter 4 - Working With Word Documents - overview
  Saving Word Documents - informational topic
    Saving Existing Documents - informational subtopic
      To save an open document - procedure
      Save Dialog Box Options - reference topic

————–
If you have any questions or comments about this article, or any suggestions for future posts, please comment on this post or email me via my contact form.
Technical Writing Tuesdays: index of posts