Keeping things simple

Building a project documentation framework

leave a comment »

Properly maintained documentation is of crucial importance to any project team and project manager regardless of project type and methodology used. Agile methodologies of today mostly advocate little to no documentation which might seem as a good idea, but in general it is a bad idea because sooner or later you will have to explain why has something been done this or that way, who order and authorized the implementation of functionality x in this specific way, the developers and tester will need to validate that requirements have been met and so on.

So when you get a supreme guru justice league developer or project manger telling you that he can complete a project without documentation don’t believe for a second that it’s a good idea. While the statement it self might be true and one can complete a project without proper documentation you can be sure that there is a whole world of pain down the road for you.

Currently I’m managing a mid-large enterprise system, that has several maintenance and upgrade contracts running concurrently which are handled by different development teams on different platforms and technologies and it is crucial for all of our teams that they have current and up-to date documentation on the system. Still we can’t afford to waste valuable man days on mountains of papers and documents so we had to choose  a proper amount of documentation which had to cover our basic needs

  • Easy to write and maintain
  • Clear and unambiguous
  • Understandable to technical and non-technical personnel
  • Easy to relate and transform to other documents

We started of with the basics of the Agile methodologies and the user story format and built our requirements document around it. The current requirements document corresponds to an Epic consisting of a scenario list like “Editing an xx”, “Searching for xx”, “Calculating xx” which consist of a story list table detailing all of the user stories required. The document in it self is a simple decomposition of the user actions which exibits the following traits

  • focuses discussion on user actions and process
  • client stakeholders can easily relate to it
  • it contains sufficient information for the development team
  • it does not predetermine any part of the actual implementation

Of course the document is always signed and confirmed by all parties project manager, client representative and development team  representative.

So we happily started to write our requirements documents and after a while when we got bug reports we saw that we could not identify how the current version of the system should behave since it consisted of user stories implemented over user stories over user stories etc. Then came the decision that we should have a document that will be updated as we implement user stories in the system will describe the current state of the system.

To satisfy that need we used the Use case form as a basis for functional description of the system. The use case document is updated during sprints by the business analysts as user stories are implemented consistently representing the current system functionality. This document covers needs different form the requirements document such as:

  • description of current system functionality
  • detailed description of required steps to complete an action or process
  • detailed description of UI
  • detailed description of implemented business rules
  • detailed description of the implementation of user stories

By developing the use cases from the requirements document we inadvertently managed to kill three flies with one blow. We quickly realized that the use case document since it details implementation and user actions, can easily in mater of an hour or two be transformed into test cases and user manuals. Then from the test cases it was a mater of a couple of hours to build automated UI test which dramatically increased the testing coverage and quality while reducing the load on our testing team.

With this we saw the ultimate benefit of keeping a decent level of documentation of our system and that is improving the overall quality with reducing costs and time-pressure development teams. The second benefit of this documentation system is that our team members can now focus on their primary job with a clear goal ahead and a clear condition of done.

The business analysts develop User stories with the stakeholders, architects review and design the system development teams concentrate on developing the best software based on User stories, the testing team can develop test cases based on the use cases and automated test based on the test cases, the support team has detailed specifications to review, test and categorize bugs, thus completing the circle and easing the job all round at the expense of investing a little bit of time in developing some documentation which comes back big time as a reward in the form of clarity of functionality, faster development and most important of all quality.

Written by Luka Ferlež

August 5, 2012 at 17:24

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: