Search This Blog

Tuesday, April 2, 2013

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


  1. Thanks, Janice, good stuff! The only tweak I would suggest is instead of documenting the feature (in #1), document the usage (or update the documentation for a particular goal/use when a new or improved feature makes it different).

    That may already be exactly what you were thinking, but I've seen too many products approach documentation by scanning the menus and making sure all the items were documented, instead of thinking about the goals of the user and providing the documentation / tutorial about how to accomplish the goal with the product.

    As an example, in visio, you want documentation about how to create data-driven shapes from a spreadsheet, which happens to include connecting the spreadsheet as a data source. You don't want documentation about how to connect to a spreadsheet as a data source.

    Thanks again,


  2. Hi Scott,
    You make an excellent point. I always assume that Agile writers follow best practices and write end-to-end user-centric documentation, but we all know what happens when you assume.

    To be honest, in item #1 in the list above, "document the feature" is a task title I use in our project management software and is just shorthand for the work that will take place. The task itself can include far more detailed information, including notes about where the information needs to live, who to contact, and so on. More importantly, when my team sees that task, they know that I'll soon be along with a list of questions. They appreciate that because it gives them a chance to hide under their desks or schedule vacation.

  3. Good article. I think one thing that is missing from this article is technology. I believe that there are great ways to be strategic about the code and tests that are written and leverage that into documentation.

    Off the top of my head, I could imagine writing documentation for a publicly accessible API. Perhaps, if Java is your language, spending time writing a custom doclet to transform the javadoc comments on your source code into a published document may help.

    Additionally, there are several BDD frameworks out there that call for tests to be written in plain english. Try leveraging something like Cucumber's gherkin language to not only specify a test, but be the initial launching point of the published documentation. As a side note, BDD tests (or tests in general) can oftentimes do a sufficient job by themselves for offering up internal documentation.

    What I'm getting at is to try to move as much of the documentation as closer to the code as possible. What is that going to buy you? Well, it should encourage developers (and everyone really) to work well with your tech writers. It should also increased shared understanding across the team and the organization of the products being built. It helps engage everyone on a team oriented effort of raising quality of code and documentation.

    That's an increase in teamwork, increase in communication and understanding, and some more increase in teamwork...because it's important. Those are some things that really help to make an organization Agile. So, why not try to extend it to producing documentation as well?

    Granted, this kind of thinking does call for some overhead to get infrastructure in place. It does call for discipline as developers (as well as tech writers) will need to be sure that code comments and tests are well written. But, wow. Think of the benefits. In a continuous deployment shop, you could write and document a new feature and watch as both code and documentation go to production with a high degree of confidence in the quality.

    1. Hi Lee - this is absolutely fantastic! While we don't have quite the code-level integration you envision, my teams have integrated all documentation into our continuous build process. I check in the doc source files which kicks off a build the same way any other code check-in does. Our build then runs the doc generation from the source files to create all the documentation targets (help, PDF, and HTML5), ensuring that each build of the contains the latest updates. Our automated tests verify help links and the entire team has access to the source doc files should they choose to update them. (So far that hasn't happened, but it remains an option.) As you point out, there might be a way to take it even farther, but the integration has been an enormous benefit in terms of both time and quality. The doc targets no longer require manual and error-prone generation and check-in, the doc source files are backed up and versioned, and the entire team has access to both source and target files for update and review. It rocks.