GUEST BLOG: 3 Ways to Make Documentation as Agile as Development

Welcome back to a colleague and friend of mine, Janice Hamrick, who is an outstanding Technical Information Engineer (aka Tech Writer) and a totally entertaining mystery writer. I read the following three ways to achieve true agility across all development team disciplines and LOVED it.   However, I felt that a fourth point was necessary:

#4 - Be Prepared to Design!

I have often thought that one of the most powerful, yet underutilized, roles of Technical Information Engineers is to make software usable. Sitting alongside of the developers while the software is being created is a huge benefit as they can answer questions like “how am I possibly going to document that???” Serving as de facto Subject Matter Experts across the product, they can also help find potential flaws and opportunities for excellent feature design and simplification. 
~ @MulticastMatt

We all know that the rules of Agile software development decree that user stories must be shippable at the end of a sprint. In other words, a feature must be fully coded, fully tested, fully documented, and fully accepted by the product owner before you can call it done.

To those new to Agile, this seemingly defies the natural order of the universe. After all, everyone knows that documentation always follows development, right? In fact, some teams so firmly believe it’s impossible to have both in the same sprint that they plan to have documentation lag one sprint behind. What they might not realize is that they are no longer practicing Agile development. Because in Agile, you’re not done until you’re done. And let’s face it:

If it’s not documented, it’s not done.

So how do you make documentation as Agile as development?

1. Make Documentation Visible

When story planning, give documentation the same weight you give any other critical-path task. EVERY story should include four documentation tasks:

• Provide content for docs.
• Document the feature.
• Review the documentation.
• Update the doc based on review feedback.

Notice that two of these tasks are the responsibility of someone other than the writer. The team commits to providing information in a timely manner and the team commits to providing thorough reviews to ensure accuracy and completeness of the documentation.

Tip 1: Don’t be afraid to mark the doc task as blocked if time is running short. You want it to be obvious that the story cannot close without its documentation.
Tip 2: Don’t skimp on the estimated hours for these tasks. If you need two different reviewers, put in twice the hours on that task or, even better, put in two review tasks.

2. Be Willing To Write Reality

Be willing to write your documentation to reflect reality. You need to document each feature as defined by the user story, even though you know that eventually you’ll have to rewrite the same topic – either to add the next new bit of functionality or to alter what was previously done because something changed. We’re all familiar with those epic stories that span multiple sprints. The developers break a standard CRUD story (CReate, UPdate, Delete) into three parts and deliver one piece per sprint. Yes, it might be easier to wait until all three are done or even to write anticipatory information, but it’s critical to be able to demonstrate the current functionality when the sprint ends. This puts you in a marvelous position of being able to ship a beta with no notice whatsoever (and yes, that’s happened to me). It also means no revisiting your topics if time runs out and the forecast development changes don’t actually make it into the release.

3. Be Willing To Write Fiction

As a semi-contradictory corollary to the reality rule, be willing to write fiction. Once a feature has been defined for a sprint, you can get started on the documentation. Creating process flow graphics, defining the scenario, providing the key background information, even updating the list of new features in the release notes can all be done before the first line of code is written. Yes, you run the risk that you’ll need to rewrite if something changes, but getting a jump start can be critical to success. You also run the risk of providing unexpected value for your team – timely user-focused questions can help the developers improve the feature as they go.

Tip: Don’t let your fiction be confused with fact. If a feature looks like it’s not going to be completed in a sprint, mark the corresponding docs with a “Do Not Publish” condition and only remove the tag after the code is accepted.

The Bottom Line
So, is it possible for documentation to be as Agile as development? As with all things Agile, success is up to the team. In Agile, everyone on the team is responsible for every story, which means everyone on the team is responsible for documentation.

As soon as your team commits to this principle, the answer is a resounding YES!

How do you keep your documentation agile? Share your tips in the comments. 

About the Guest Blogger

Janice Hamrick joined CA Technologies in 2010 as the Senior Technical Information Engineer for the Capacity Management suite of products (formerly Hyperformix).  Before joining Hyperformix, she spent years writing documentation for backup and recovery products for a rival company whose three initials shall remain unnamed. It is a myth that she has worked as a technical writer in the software industry since dinosaurs roamed the earth, but she does remember when “agile” was something you had to be to avoid the saber-toothed tigers.

Outside of work, Janice is the author of the award-winning Jocelyn Shore mystery series (DEATH ON TOUR and DEATH MAKES THE CUT, Minotaur Books).  She has completed the third novel in the series which will be published in 2013 and is currently working on a new and much darker mystery series.  Learn more at www.janicehamrick.com.