Project documentation: Just enough just in time.
One of the projects I work on has lots of documentation; functional design documents, technical specification documents, interface design documents, etc., etc. These are mostly so there is agreement about what is going to be built and as a reference afterwards for the teams that work with and maintain the system. Having lots of documentation makes some sense, gives some assurance and confidence, but it takes a long time to write and agree.
I’m also working on another project that as yet, has very little documentation. And one of the things we need to figure out as we progress through this project is how to document it effectively.
So how much documentation is enough? How do you get the right amount of the right kind of documentation at the right time? I think it should probably start with understanding what you aim to achieve. If you want documentation that enables you to all agree what to build, that should be different from documentation that records the results of testing, which is going to be different from documentation that creates an encyclopedic knowledgebase that enables other developers and users to be able to understand the decisions that were made during building.
For our project, my aim is just enough just in time. The documentation should grow with the project, alongside it, and at the same time. So the first step is high level requirements that enable us to complete the discovery work. We’ll then figure out the next phase and what documentation is needed to support that. It might be that the high level requirements evolve into user stories or more detailed business requirements, but this evolution will provide just enough information for the next phase just in time for the next phase to start.