My last technical documentation post on remembering the audience reminded me of the importance of designing the documentation set for the product you are working on.

Knowing the audience is a critical part of writing a manual. I like the approach of having a short introduction section where all manuals follow the same structure.

Standard sections I like to include are

• Purpose: What the intent of the manual is
• Scope: A summary of what topics are covered and not covered by the manual
• Audience: Who the manual is intended for (programmer, end user, administrator, installer)
• Conventions: a summary of styles used in manual and what they mean

Purpose and scope are often mixed up. Purpose is about why the manual exists, and scope is what is covered.

The audience section is important. It is useful for the reader, but it is even more useful for the author! Something to remember is manuals will probably be edited many times after the first version is completed. There will also probably be multiple people who contribute to the manual over its life. Putting in these sections are just as useful for the authors to remind them of the scope, purpose, audience etc so any contributions are in line with the objectives of the manual.

Here are common types of audience.

• End users who are the users of the system
• Administrators who are responsible to ensure the correct operation of the system
• Installers, who may be the Administrator as well, or may be a systems administrator
• Programmers who want to extend the product or integrate it with other systems

The conventions section is useful to encourage consistency of formatting (e.g. mono-spaced text for source code). If you find this section getting too long and complex, you probably have a problem to work through.

So, given the above standard introduction to manuals, what sort of manuals should you develop?

• If you have more than say 3 manuals, I like having a documentation roadmap. It lists all of the manuals included in the documentation set, the audience, purpose and scope. This document should be short. But it tells the reader what exists and what does not, and helps them choose the right manual to read.
• Realizing that the person who installs the software may be different from the person who is responsible for looking after the system results in separate manuals for
  • Installation manual – written for someone who does not necessarily understand the system, but is responsible to log in as root to get it installed
  • Administration manual – this may cover admin interfaces and configuration files
• Guides are important to show use cases and how the product supports those use cases – they don’t try to teach everything, but rather show how it is meant to fit together it one answer – they are like a trail guide through the jungle allowing the reader to get a better idea if the big picture
• Reference manuals cover every single feature, legal syntax if configuration files, and so on – Javadoc may be included here if appropriate

I frequently use the reference manual as a form if technical documentation. I like to put enough into it that the high level design is somewhat clear. The advantage is there are fewer total documents to write. Care must be taken not to lose the reader due to the depth.

A final parting thought – the documentation is in effect a contract between the product developer and product user. If the product does not do what the manuals says, it’s a bug. To fix bugs, it may be the documentation should be corrected, the documentation extended (if the documentation does not say what should and should not happen), or the product fixed to match the documentation.