Working software over comprehensive documentation
This leads to a lot of misunderstandings in organisations that are considering one of the Agile flavors as a new way of working, especially when they are used to document a lot. Quite often we need to start explaining that Agile does not mean “no documentation” but that we will handle it differently. And that’s exactly what this article is all about:
- something to reassure everyone that documentation is still considered important
- a quick reminder to myself, something to keep in the back of the head
At the same time a big “Thank You” to Scott W. Ambler for even more elaborated context.
The basics of Agile documentation
Let’s begin with some fundamental advice:
- Prefer executable specifications (Examples: C.I., ATDD, Clean code instead of javaDoc, Stories + SubTasks) over static specifications (documents like excel, word, powerpoint…)
- Single source information for everything, preferably a Web 2.0 solution like a Wiki space.
- 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
Considering the above specified context and the image, we should follow some guidelines before deciding to create documentation. We should think about documentation as a requirement and as such follow these steps:
Evaluate the documentation request thouroughly
- For whom are we creating this documentation?
- Why does he/she needs this information? What problem will we solve with the documentation?
- Are there other ways to obtain this information? Higher in the chain of communication effectiveness and already in place (demo sessions, planning sessions, tasks identified on stories…)
- Is the effort (= cost of documenting) exceeding the value (= cost saved for the requestor)? Or evaluate the TCO of creating the documentation.
If needed, keep it simple
- Keep the document simple
- do not use templates
- do not write 50 pages if 5 will do
- do not write extensive proza if a simple sketch will do
- do not repeat, use references instead (cross linking is allowed)
- …
- Travel light and do just barely, good enough!
- Collaborate with team members and especially the requestor. Use the right tools, Web2.0/Wikis are there for you as well, don’t stay in the 80’s using whatever old-school heavy documentation bank you still have lying around,…
- Display information publicly as this is promoting transfer of information and will help the organisation be successful.
- Document with a purpose having a focus on the actual needs.
- Iterate, iterate, iterate… (let it grow and adjust along the way)
- Find better ways to communicate. (see right side image)
- Update only when it hurts!
What to avoid?
- The requester wants to be seen to be in control.
- The requester mistakenly thinks that documentation has something to do with project success.
- The requester wants to justify their existence.
- The requester doesn’t know any better.
- Your process says to create the document.
- Someone wants reassurance that everything is okay.
- You’re specifying work for another group.
(For more details about these points check out this essay)
The vision on Agile documentation
(SDLC = Software Development Life Cycle)
The system
A web 2.0 enabled collaborative platform: Confluence Wiki for example
Confluence wiki
- Tightly integrated with JIRA workflows
(Note: avoid tools for work alignment, use walls and post-its instead) - Versioning, full history tracking available
- Signing off = closing page
- Use Gliffy for confluence for drawings, UML’s, Wireframes…
- NOT: do not use the wiki as a document storage, instead use the wiki to document in directly!
- And most important: COLLABORATE
- …
You can find very detailed descriptions on producing documentation the Agile way and the reason why to do it differently in this Agile Modeling Essay and these Documentation Best Practices.
Find out what Confluence Wiki can do for you.