I have been looking at standardizing some document templates for various software artifacts. As I review these things, there are several items that annoy me. As I think about it, I think the difference comes to how the documents are viewed (and in particular whether they are handled in hard copy vs. looking at them online).

Typical documents I see look like this:

  • Title Page
  • Revision History
  • Table of Contents
  • Bunch of standardized boilerplate text mixed with the content I am interested in

    • Many times, I need to page through 3-5 pages before I get to the information I am interested in.

    Title Page: In a printed document, this may or may not be a nice touch. However, generally, it does not add significant value over just a title, author and update date at the top of the first page of text. Whether to include a title page or not in the printed document is a question of your audience. In an electronic document, this is text and whitespace that must be skipped over to get to the “meat” of the document.

    Table of Contents: If I see another 3 page document with a table of contents, I think I will scream… My general rule for printed documents is that a table of contents is useful once the “meat” of the document is over 10 pages. In an electronic document (where I have full text search), I want the table of contents to be hyper linked enabled so I can use it as a navigation tool.

    Boilerplate Text or Background Info: In a printed document, it is a matter of preference. In general, I prefer background information on a project to be kept in a separate document that is referred to in the main document. However, this may make using the printed document unwieldy if the reader needs to shuffle between multiple documents. In an electronic document, I want the background information to be a link to the definitive source. It is easy for me to skip over and if it changes, there is only one location that needs to be updated.

    Boilerplate text is often seen in document templates. These are usually instructions for how to use the template or perhaps generic text that describes corporate policies or procedures. This text may be useful to a new employee or someone who is using the document for the first time. However, after that initial experience, this is text that most people will skip over and generally ends up wasting space. If instructions are needed or a reference to a procedure needs to be included, make it a reference (or link) to another document.

    Revision History: Some documents include a detailed table of every change made by every person ever in the history of the document. While this is valuable information, I consider this document meta-data rather than content of the document itself. I would prefer to see this data stored in the version control or content management system rather in the body of the document. That being said, it is nice to have some version identifier in the document (perhaps in the header or footer) to distinguish between versions.