Unnecessary Documentation

The first section that I look for in a document, is the paragraph that describes ‘who this document is written for’ and ‘what benefit they can expect to gain by reading this document’. If I do not see my role, or I do not see any benefit from me spending time reading the document, then I have to ask myself the question, ‘Do I want to read this document?’ I want this information to be displayed to me asap, such that I waste as little time as possible, reading a document that is of no interest to me.[1]

When I review a document or document template, another task that I might perform, is to consider each section in the document and ask the question, “Who asked for this information to be entered into this document?’ Or, another way of putting the question is; Who is going to read this and get value from it?[2]

Typical subsequent sections of a document I have seen that need this question applied include:

• Document History – How many readers want to know what changed between versions from 1.1 through to 1.15?
• Definitions and acronyms – leave them in the glossary, nobody needs to read these in the document. If anything I want to be able to reference these while reading the document without having to leave the current page. (See also ‘Duplication’.)
• References – Put the reference in the section that uses it. I do not need to see a separate page containing a complete list of document references. I am not going pull up all the referenced documents and have them prepared in case I come across documentation that makes reference to one of them.

Before you document something, find out who it is that needs this information documented.

Which leads me to ..

Document Content Organization

On a related issue: There are tools for recording document versions. Any decent tool that is intended as a central repository for files of any type will record the version of the document and allow the author to add comments to the version. Such tools include SharePoint, LiveLink and ClearCase amongst many others. So why is it that when I open most documents, one of the first things to be presented for my reading pleasure is a table containing a version history. Honestly, I have seen version histories that span many pages and are quite detailed. They explain every change that has been made to the document over the last Millennium. Who wants to read this stuff, and why is it the first information that is presented to the reader after getting past the front page? If we are using a document management system on this project, (and I certainly hope that we are) all of the version history information should be documented inside the tool. Why is it being repeated in the document?

Many years ago, before the advent of intelligent document comparison tools, this information may have been useful in the front of the document. It allowed to reader to determine which parts of the document have changed since the last time they read it. Today, any Word processor worth purchasing will inform you what has changed since the last time you reviewed the document.

I realize that there are some roles on the project to whom this information is important, QA or auditors, for example. If you must publish this information with the document, put it in an appendix to the document, or better still, extract it from your document management tool into its own document. Then distribute the version history document only to those people that want it.

Now that the version history is out of the way, what do we now see when we open the front cover of the document? The table of contents. It is useful to be able to easily locate this, but I question whether it is the first piece of information that I want to read. What I need to know, as soon as possible is, ‘Should I be reading this document?’ What is going to answer this question – the Introductory material in section 1.

1. The first question I want answered is; Is this document describing a system that I am interested in?
2. The second question is; Is the information in this document pertinent to my relationship with the application?
3. The third question is; What information am I going to get from this document?
4. Fourthly: What is my responsibility towards the information in this document?

Hopefully, the answers to these questions become apparent as soon  as I open the front cover of the document.

Put the appropriate information in the appropriate place and avoid showing unnecessary information to the wrong people.

Editor's Note: Check out the list of all related best practices.