The Community Blog for Business Analysts


Best Practices - Inconsistent Documentation

If you are writing a letter to your mother, it is fine to create a new a new blank document, type your random thoughts, add highlighting, colors and emphasized text where you want to make and get a point across, and basically format the document with any creative ideas that you feel appropriate.

When working with documents in the workplace, ad hoc formatting is probably not appropriate. Yet I see so many requirements and other technical documents that were written by people who thought that they were writing a letter to their parents.

Imagine if every programmer on the development team wrote source code using their own personal coding standards. Nobody would be able to maintain someone else’s code. It should be the same with documentation. Every document should be written from a predefined document template that includes documentation standards (instructions for use), a consistent set of styles and properties.

The problem not only applies to textual documents, but also to diagrams. UML for example, defines a set of artifacts in terms of a set semantics and rules that apply to that artifact. (As far as I am aware) the icons used to represent an artifact are not defined within UML standards. Not only that, but UML allows the stereotyping of defined artifacts, which in turn leads to a customized representation of the artifact.

An example, I might be, using an arrowhead to indicate the initiator of a use case (which I do), and someone else using a dashed line to indicate the same thing. Now there needs to be an explanation in each document of the meaning of which notation that is being used. Not only that, but if both diagrams contribute to the same document, you are going to confuse your readers.

Use a set of rules for identifying a particular meaning on a diagram. If there is no rule for it, then make one up and explain what the particular notation means (although the more project rules there are , the less explanation needs to be added to the diagram or document). Say for example, you wish to highlight parts of a diagram to indicate that they are candidates for change, but there are no project specific rules for indicating how to highlight changing components. Then go ahead and shade the items (or whatever highlight you prefer) and explain what the highlighting means.

Which leads me to; the number of times I see a figure in a document without, not just a description of the figure, but not even a reference to it. Why did you put this figure here, if you are making no reference to it?

If there are 2 ways of doing something, pick one that works, describe it and stick with it for the length of the project.

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

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

Related Articles


Leslie posted on Friday, March 19, 2010 2:10 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