The Product vs Project dimension

Why should you be making this distinction?

If you are not making it, you probably recognize some of these issues:

• you are redescribing your product over and over again for every new project
• there is no documentation of your product as a whole, in stead pieces are described depending on what was relevant for the project
• It is hard to find existing documentation as it is organized per project in stead of per product

What

Product Documentation

Product documentation describes your product as a whole and it is meant to be kept for as long as your product is out there. Classic artifacts are for example:

• use cases: giving a complete functional view on the product
• information model: describing the information relevant for the product
• the design and interactions with other products

Your product documentation will follow the evolution of the product, e.g. if the behaviour of your product changes, your use cases will most likely need to be brought up-to-date. While this documentation can be very valuable, a developer or tester will not want to receive the complete list of use cases when he's working on one user story. That's why we also need Project Documentation.

Project Documentation

Your project team will need a consolidated deliverable describing:

• the requirement, for example expressed as a user story, with its context and acceptance criteria
• the relevant parts of the product documentation
• depending on what is needed, you can enrich this with other aspects such as a wireframe or a numerical example, i.e. whatever you need to explain and clarify the story.

This type of documentation loses its value once it has been implemented and no longer needs to be kept up-to-date.

Just to be clear: If you've read my previous posts you will know that I'm not a fan of throwing documents over the wall. The project documentation does not replace communication, but serves as a reminder of what needs to be done.

When

In my experience, documentation hardly ever gets written after the fact. By the time the features have been developed, analysts will be busy testing or are already working on a new project. This is why I prefer documenting as soon as the solution is chosen. It can furthermore be quite demotivating for an analyst to document features that have already been implemented.

How

There are mainly two situations: creating a new functionality and changing an existing functionality.

Product Documentation

I always start by adapting or creating the analysis of the product. This way the product documentation is immediately up-to-date.

Project Documentation

New feature
For a new feature you can just list the relevant parts of the product analysis per user story.

Change request
When it concerns a change request I make sure I list all the changes I made to the product documentation per user story. Otherwise I will find myself forgetting what needs to be adapted, added or removed.

This post is based on an entry from my personal blog. I hope you enjoyed it. Let me know what you think!

Like this Blog?

Then you’re in for a treat! Visit Sarah Denayer’s personal blog, which offers many more hours of excellent reading material!