Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Agile Documentation: Fact or Fiction?

DZone's Guide to

Agile Documentation: Fact or Fiction?

Learn about three key practices for creating effective Agile documentation and how they tie into the principle in the Agile manifesto about simplicity.

· Agile Zone
Free Resource

Reduce testing time & get feedback faster through automation. Read the Benefits of Parallel Testing, brought to you in partnership with Sauce Labs.

Image title

Documentation in an Agile environment is an interesting topic. The Agile Manifesto places more value on working software than on comprehensive documentation, and one of the Agile principles states, “Simplicity–the art of maximizing the amount of work not done–is essential." But does this mean we shouldn’t write documentation when we use an Agile framework? Not at all. I use these three key practices to create effective Agile documentation.

Minimize Artifacts

First, minimize documentation to just what’s needed to get the job done. While software solutions must be maintained and need supporting documentation (either as commented code or external documentation), there is a tendency to create documents simply because “we’ve always written them," whether they are ever read or not. Creating unneeded documents expends valuable time and is counter to delivering the highest value first. Documentation effort should be treated like a requirement if it’s not part of your Definition of Done; it should be estimated and prioritized along with other work. This means weighing the cost of documentation against the anticipated benefit.

Simplify Efforts

Second, simplify document creation effort. My philosophy for simple documentation is 1) do only what’s needed, 2) do it quickly, 3) do it as simply as possible to serve its purpose, then 4) move on. For example, instead of spending hours perfecting a Visio document so everything lines up, the colors don’t clash and the fonts are cool looking, take five minutes to hand-draw the diagram on paper, scan it and store it where the team can access it. Also, keep documentation as succinct as possible while still conveying the needed information. Draft it, review it, get rid of the fluff and finish it.

Document Later

Third, create the artifact at the proper time. Just as “big-requirements-up-front” (a waterfall practice) is usually less effective, so is documenting concepts or solutions too early. It often makes more sense to wait until features become somewhat stable before you document them. Documenting later typically reduces rework caused by changes that inevitably occur. However, if documentation is put off too long, you run the risk of undocumented software if resources are constrained or reassigned before documentation is completed. Many agilists prefer building time into each user story for the necessary documentation. In these cases, the “Definition of Done” should specify what adequate documentation means.

The bottom line for effective Agile documentation is to create a document only if it fulfills a useful purpose, keep it simple, and do it when it makes the most sense to reduce rework.

The Agile Zone is brought to you in partnership with Sauce Labs. Discover how to optimize your DevOps workflows with our cloud-based automated testing infrastructure.

Topics:
agile adoption ,scrum ,lean ,kanban ,documentation ,business analysis ,product owner ,scrum master ,agile best practices

Opinions expressed by DZone contributors are their own.

THE DZONE NEWSLETTER

Dev Resources & Solutions Straight to Your Inbox

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.

X

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}