We need documentation to help us achieve optimal communications and control; however we also understand that documentation can be an overhead that doesn’t add value to our customers.
There are two types of documentation and you should always be aware of why you are writing documentation and for whom.
Project documentation is for communication
Project documents are used for communication within a project and are not maintained once the project is completed. These documents are necessary to:
- Sell the concept
- Remove ambiguity
- Facilitate a multi-location team
- Manage the details
Product documentation is for management and control
Product documents are used for managing and controlling the product and will be maintained until the product or feature is retired. These documents are necessary to:
- Manage priorities and scheduling
- Maintain quality standards
- Maintain correctness
- Educate people
When you’re using documentation to communicate, then you’re capturing the state of the requirements etc at a given point in time. If the requirements change, then you don’t update your original communication, you make a new documentation to communicate the changes clearly.
Communication isn’t a living document.
However, when you document for education, then it is a living document. If the requirements or scope changes, then anyone reading your old document for education purposes will be misled, therefore in order for your document to meet its purpose, it has to be maintained. This means every time you write a document for education purposes, you’ve just added an overhead to your project – a document that has to be updated as the project changes. If you are not going to maintain the document – then you aren’t writing it for educational purposes. To make the maintenance cheaper, the document can contain less detail and more principals that are less likely to change.
I’m in the middle of re-defining / designing our design and development process.
I’m interested how you combine an Agile approach with documentation for communication. I can see the value in sending a new document (to a client) because doing this makes it clear that change has occurred. What I would like to know more about is how you create and use communication documents within a project.
For example, if working in an Agile way I would expect a Functional Specification document to be a living document – in an ongoing process of creation / editing / change – for an important part of its life. It would act as a common record of specification state as functionality is negotiated and research / testing done to establish just how various features should function.
Maybe the implication of your blog is that a Func Spec should be a folder of communicated documents, some of which supercede each other, rather than be a single (and very edited) document. I look forward to reading more of your thoughts.
Paul
Paul – if making changes to a single document is the best way to communicate, then that’s better than keeping separate documents for each change. Do whatever makes communicating most efficient.
The difference between project and product documentation isn’t so much during a project, but after it. Will you keep that functional spec up-to-date after the project has finished? If so, it becomes a drag on the product so it better be worth it. Quite possibly it is worth it, but if you’re only ever going to use it to regression test, then it could be more efficient to write a test script and keep that script up-to-date, while the functional spec remains a record of that project.
Its just a matter of being deliberate about why you are writing documentation and who its for.