“Essential: Document with just barely good enough detail.
Valuable: Document only when we actually need it, not when we want it.
Timely: Documentation should be done in a just-in-time (JIT) manner, when we need it.”
Ashish Sharma, here
The Manifesto for Agile Software Development values “working software over comprehensive documentation”.
This ethos is particularly relevant for OSS projects. A document exists to communicate in ways that are more practical than via verbal communications such as for large audiences, remote audiences or future audiences. OSS projects can have elements of each of these.
They may need to communicate to large audiences, particularly customers.
They may need to communicate with remote members of the project team or customer team.
They may need to communicate with people who are picking it up in the future such as maintenance teams or new starters at the customer.
All valid reasons to document.
But the end must be in mind when writing the document. If you work from the agile premise that all documentation is wasteful, ask what is the least amount of documentation you can proceed with, who can afford the time to create it, can it be discussed rather than documented, can it be created progressively in-flight when is it needed) and who needs to be convinced of the need to reduce or remove certain documents from the deliverable list?Read the Passionate About OSS Blog for more or Subscribe to the Passionate About OSS Blog by Email