Project documentation

I got the following questions from a friend who wants to understand agile practices prior to implementing them on his project. I will try to answer them based on my experience.

” What needs to be documented in agile ?”

The Agile principle is “Working software over comprehensive documentation”. Documentation can be an intermediate product towards delivering this working software. It can be created for reference or for articulating business rules and in case of distributed development, to communicate ideas.

Chris Matts puts this well – The real aim is to build the knowledge in the minds of the developers and business users rather than focus on creating a document that may well not be used.

Having said that, there are real requirements to produce documentation as an end product such as for legal compliance or for product patents. Sometimes documentation is required for future support activities, but there are other better ways to handle these requirements.

“How do stories get documented ?”

At Thoughtworks, we have developed a practice to determine project /programme requirements in facilitated workshop sessions. Stories are captured during those sessions, typically by the clients themselves, using the following format.

As a .. <user who requires this feature>
I would like .. <goal>
So that… < business justification

The stories captured in this fashion supported by process flows and scenarios are sufficient for estimating and prioritising and thus, for further planning.

During the development phase, the stories prioritised for development are further corroborated with acceptance criteria, a set of conditions that the story must fulfill to be considered complete.My colleague Dan has an excellent article describing the intent and the anatomy of a story in detail.

“Are the story documents kept after its been implemented ?”

XP practitioners derive a catharatic experience from tearing story cards after they have been implemented.

In practice, the story documents are largely captured electronically either on the WIKI or in Word/ Excel documents or as automated acceptance tests – so does not make sense destroying them. The supporting documents that you build around documenting your business rules, UI design or implementation logic are useful even beyond the implementation.

We have used FIT tests as living documentation which live beyond the development phase. During development, they are useful for specifying acceptance criteria in a testable form and beyond that, they are useful as a regression test suite.

“How are the stories organized ?”

I like organizing my stories on the WIKI as that gives you multiple advantages. WIKIs allow you to have a view which lists the entire scope of development by listing the stories, their status, their priorities etc. You can have individual page/placeholder for each story which you can flesh out as they get prioritised for development.You can have another view where you can reference the stories by iteration. Multiple views are useful for all the stakeholders in your project including your client, project manager and the development team.

We have also used Trac , JIRA and Sourceforge for organizing the stories. Based on Thoughtworks’ collective experience in project management, our product division would shortly be launching an integrated project management tool called Mingle , which I expect to start using on our projects.

“How are they kept for future references ?”

As for maintaining documents for future reference, it is better for the existing development team to summarize the whole project as it has been implemented in a seperate document. Future reference requirements usually stem from the need to support or enhance the existing application. So important decisions taken during the project such as key architectural decisions, business rules, workarounds and UI flows can be very useful context to a new person on the project.

Support artifacts also need to be created in the context of the audience and the intent. For example, a working prototype of the application was extremely useful as a training tool for the internal staff instead of a wordy user manual in a previous project I worked on.

“If a feature is changed in the future is the same story accessed again and modified?”

The simple answer is no. You should create a new story for the same. You could mark the original story to say it has been superseded by a new story. Stories are also planning units and there are implications on project velocity* calculations and scope management that need to be considered here.

If your documentation is a living documentation like FIT tests, you will need to change the original documentation for it to stay relevant.

I would be interested in getting more perspectives on the above questions myself. So if you have wisdom to share, drop some comments here.

* – Project Velocity is the throughput of the team in a fixed period of time measurable in a unit of business delivery (Thanks Dan)


5 Responses

  1. Great summary! Quite objective.
    I have one question related to the “How are the stories organized ?”
    When you organize your stories on wiki, what do you put? The status, priority, any other?

  2. Really makes you think, doesn’t it?

  3. thanks for highlighting the nuances of project documentation. It really helps.

  4. I have refined what I posted on my blog about what it means to be agile and I initially equated it with the amount of documentation one writes. I still believe that to some degree. The Story and its documentation is key to all projects and I appreciate your post on this, thanks.

  5. […] Article en anglais : Project documentation […]

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: