Agile OSS documentation

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

2 thoughts on “Agile OSS documentation

  1. Of all the things in the Agile Manifesto, that statement about documentation is the one that annoys me most.

    OK, I’m a product manager, and Agile was originally born out of engineers’ frustration with water-fall design/dev cycles. But still, the Agile Manifesto highlights much that is wrong with how skilled, enthusiastic engineers approach a problem by coding first then designing later.

    Rant over.

    That said, as Agile Dev matured in the many years since the manifesto was published, it has become a useful tool for engineers and product managers alike. I’ve seen it done well in OSS, and I’ve seen it done so badly it almost destroyed an OSS company, literally, because they thought Agile meant not needing to know what they’d be committing to or doing in 3 months time…

  2. Hi James,

    Rant acknowledged for the great points raised James! 🙂
    I completely agree with you in your statement about there being a massive disparity between agile done well and agile done badly. The whole premise of agile concerns me in that there is the potential for it to wander along aimlessly in short-term thinking if there isn’t someone (or a group) that is steering the ship to the desired port.

    I’m a big believer in lean documentation (as per the quote from the manifesto), but I definitely don’t equate that to lean design and especially not to coding before designing (acknowledging that design and documentation can be closely linked at times, but not always).

    I’ve seen too many instances of bloated documentation getting in the way of projects, being created purely as a deliverable with no useful purpose and/or used as procrastination devices. One example is of a design document that provided a workable solution at approx. 30 pages, but ballooned to nearly 200 covering loads of boundary cases that were never going to eventuate. Not only did this document delay the project by 3+ months, but it probably would’ve cost hundreds of thousands of dollars to produce when considering the number of review cycles and number of very senior reviewers involved.

    Conversely, I’ve seen 100+ page design docs that have taken months of preparation that have been worth their weight in gold due to their ability to inform and persuade large audiences.

    The aim of the post was to highlight the need to do pre-plan a rough cost-benefit analysis of documentation – is it likely to deliver sufficient value for the time/effort/money that will be expended? Who is the audience and will they find it valuable? More often than not the answer is no. Your comment provides some great alternative perspectives. Thanks for sharing James.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.