Introduction
- Agile Manifesto focuses on working software over comprehensive documentation
- Agile became the popular alternative to massive development methodologies that favored processes, tools, and rigid planning
General Points
- Documentation effort may be a few iterations behind your software development effort
- Actively explore how they intend to use the documentation and why they are using it that way
- The benefit of having documentation must be greater than the cost of creating and maintaining it
- Developers rarely trust the documentation, particularly detailed documentation because it’s usually out of sync with the code
- Each system has its own unique documentation needs, one size does not fit all
- The true value of documentation the increase understanding of the problem domain, or the solution domain in the case of architecture/design
- Document with a purpose, the creation and maintenance of a document is a burden on your development team, and if you want to increase someone’s burden you should be able to justify why
- Effective documentation is a balancing act, the goal being to have just enough documentation at just the right time for just the right audience
- Executable specifications offer far more value than static documentation
- Code documentation versus external documentation
- Quantity versus quality
- Document stable things, not speculative things.
- Travel Light
- Agile documents do not capture obvious information
The goal in Agile should be to find the right balance between documentation and discussion. Documentation is an important part of every system, Agile or otherwise, but comprehensive documentation as such does not ensure project success. In fact, it increases your chance of failure.
Documentation should take on a collaborative nature. It should not be written by one person to perfection, and then shared with others. It should instead be shared often during draft to gain input.
Focus on just barely good enough documentation and avoid big upfront details which typically means a lot of guessing and wasted time. Barely good enough means document what you currently know.
Documentation can take many forms. It is not only a Word document, documentation can live on a wiki, in the Agile planning tool, as comments in code, and much more
The Extremes
At one end of the spectrum are projects where no documentation is written at all whereas at the other end no software is written at all, neither extreme is likely to be appropriate for your situation.
Relationship between Models, Documents, Source Code and Documentation
- a document is any artifact external to source code whose purpose is to convey information in a persistent manner
- a model, which is an abstraction that describes one or more aspects of a problem or a potential solution addressing a problem
- source code is a sequence of instructions, including the comments describing those instructions, for a computer system
- documentation includes both documents and comments in source code
Types of common document needs
- Contract models
- Executive Overview/Vision Statement
- Operations manuals
- System/Project overviews
- User documents/manuals
- Training materials
- Support documents/manuals
- *Design decisions
- *Requirements document
See this post for a detailed table
When to create a document
- Your project stakeholders require it
- To define a contract model
- Supporting mechanism for communication with an external group
- Supporting organizational memory
- Audit Purposes
- Think something through
Some rule of thumb laws
- Prefer executable specifications over static specifications (documents)
- Single source information
- Document stable concepts, not speculative concepts, and thereby document as late as possible in the life cycle
- Documentation is the least effective means of communication
When Should You Update Documentation?
- Update Only When It Hurts
- Update contract models and re-release them ideally before, and minimally in parallel to, releasing the item(s) that the model describes.
- Documentation that is intended as part of the system, such as operations and user manuals, should be updated and released before or with the system itself.
- The customer of the documentation is being inordinately harmed, including a significant loss of productivity, because the documentation is not updated (e.g. it hurts).
Effective Documentation Handoffs
- Avoid documentation handoffs
- Avoid documentation handoffs
- Avoid documentation handoffs
- Support handoffs with other means of communication
- Write agile documentation
Approaches
- Write deliverable documentation continuously throughout the project
- Leave the finalization of your deliverable documentation to the end of the project
When to Document
- When the reasons behind the decisions that you made are important to record
Why Documentation may be necessary
- lightweight user stories and requirement artifacts work really well for construction, they may not be sufficient for ongoing maintenance
- agile documents are often very minimalist without the overview often needed by a maintenance team
When is a Document Agile?
- When they maximize stakeholder ROI
- Stakeholders know the TCO of the document
- When the documents are “lean and sufficient”
- When the documents fulfill a purpose
- When the documents describe “good things to know”
- When the documents have a specific customer and facilitate the work efforts of that customer
- When the documents are sufficiently accurate, consistent, and detailed
Audit Documentation
- In some industries there are outside rules and regulations that applications must comply with
- Traceability is important in large projects
- Auditors need documentation that demonstrates compliance
- Consider providing maintenance and audit documentation as separate deliverables produced as part of the iterations
- For audit documentation, get the full requirements and make them part of the story
- Involve people with an auditing backgroung into the process
Best Practices for Simplification
- Keep documentation just simple enough, but not too simple
- Write the fewest documents with least overlap
- Put the information in the most appropriate place
- Display information publicly
Forms of Agile Documentation
User Stories
Misconceptions
- if a individual/team doesn’t perform one can take the documentation that was produced and provide it to the next contractor who will start from there
References
Agile/Lean Documentation: Strategies for Agile Software Development
Is agile documentation an oxymoron?
Best Practices for Agile/Lean Documentation
Documentation in Agile: How Much and When to Write It?
Agile Technical Documentation
Document Continuously: An Agile Best Practice
Documentation in an agile world
