Just Enough Documentation

17515 Views

1 Comments

7 Likes

Author: Jan Kusiak

Just Enough Documentation: How much is enough? Is documentation a blessing or a curse? If you’re working on an agile project does it get in the way? If you’re updating a core system that runs your company’s business, are you cursing the analyst who didn’t adequately document all the business functionality? Is today’s agile project tomorrow’s core system?

How much documentation to produce is one of the most troublesome issues facing analysts today. There are no hard and fast rules on this and successful projects define their own rules to fit the circumstances and organisation.

However one thing every project has in common - there is always some documentation even if it’s only a terms of reference. Not many projects get signed off based on a verbal business case - at least the company accountant hopes not! Here are some guidelines to consider when producing your next set of documentation.

Follow the money – the project Terms of Reference
Does the client know what they want?
Describing functionality – user stories or requirements specifications?
Talking to the technical folk
Modelling
Maintenance – it comes with the territory
So how much is enough?

COMMENTS

Tony Markos posted on Wednesday, December 8, 2010 7:46 AM

What is just barely good enough functional modeling? To summarize a large part of what Scott Ambler says at www.agilemodeling.com: A quality big picture model that captures the unchanging [business] essentials and that is both cohesive (i.e., integrated) covers the required breadth - which, for an enterprise wide effort, may be the entire organization. Scott says that just barely good enough modeling is not poor quality modeling.

Unfortunately niether use cases nor story cards guide the business analyst through proper integration. That is to say neither has a litmus test to ensure that the essential interrelationships have been identified.

And neither use case or story cards guide the business analyst in insuring that the model is comprehensive. Example: With either technique, how does the BA know that he/she is done with analysis?

Tony