The Community Blog for Business Analysts


Best Practices - Document Content

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.

[1] Typically, I expect to see this section, right after the document overview, which tells me that I am not a part of this project anyway.

[2] If the content is relevant, then I might ask if this information is implied within the section that describes the ‘Audience’ for the document.

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

This entry was published on Mar 15, 2010 / Leslie. Posted in Requirements Management and Communication (BABOK KA). Bookmark the Permalink or E-mail it to a friend.
Like this article:
  3 members liked this article

Related Articles


Leslie posted on Friday, March 19, 2010 2:12 AM
These blogs read a bit terse and out in left-field when read by themselves.
It might help to read preceding articles on best practices starting with:

Only registered users may post comments.

Modern Analyst Blog Latests

As we start a new year many of us will take the time to reflect on our accomplishments from 2012 and plan our goals for 2013. We can set small or large goals. goals that will be accomplished quickly or could take several years. For 2013, I think Business Analysts should look to go beyond our traditional boundaries and set audacious goals. Merriam-...
Recently, I was asked by the IIBA to present a talk at one of their chapter meetings. I am reprinting here my response to that invitation in the hope that it will begin a conversation with fellow EEPs and BAs about an area of great concern to the profession. Hi xx …. Regarding the IIBA talk, there is another issue that I am considering. It's p...
Continuing the ABC series for Business Analysts, Howard Podeswa created the next installment titled "BA ABCs: “C” is for Class Diagram" as an article rather than a blog post. You can find the article here: BA ABCs: “C” is for Class Diagram Here are the previous two posts: BA ABCs: “A” is for Activity Diagram BA ABCs: “B” is for BPMN


Blog Information

» What is the Community Blog and what are the Benefits of Contributing?

» Review our Blog Posting Guidelines.

» I am looking for the original Modern Analyst blog posts.


Copyright 2006-2024 by Modern Analyst Media LLC