How to manage documents? Should that be a new story?

August 28, 20172 min

Continuing with our discussion of documentation, I wanted to address how we actually build these documents within our Sprints (or iterations).  Remember our key Agile principles related to documentation: “working software is the primary measure of progress” and “the most efficient and effective method of conveying information to and within a development team is face-to-face conversation.”

I do NOT recommend having a separate user story for writing documents for multiple reasons.

  1. By definition, user stories describe how working software solves a problem, or fulfills a need, for a user.  Documents are not software.
  2. Every user story must be something you can demonstrate.  So how do you demonstrate a document to a user?
  3. A user story needs to be something valuable in the eyes of the user.  Certain types of documents, like those specified in a contract or required for statutory reasons, would be considered valuable, but for the most part documents are considered (a sometimes necessary) waste.

Another way to track manage documentation would be through the Definition of Done (DoD).  Since the goal every Agile process is to have shippable software at the completion of each iteration, that means in addition to new functionality, the software needs to be appropriately documented.  Use the DoD to be 100% clear about what are the documentation requirements in order to say a feature is potentially shippable.  Any feature that does not meet the DoD is not allowed to be demonstrated.

Finally, there are no iterations (or Sprints) to create the documentation since that would break the rule that every iteration needs to deliver working software.  If a document is needed, I recommend creating it along side with the feature.  Remember, most of the technical documentation is contained either in the code or the automated tests.  Any other required documentation would be created just-in-time as the feature is close to being completed.  I often recommend including the formal review of the documentation (if needed for your product) as part of the acceptance criteria for the feature.

We need to remember that working software is the primary measure of progress of the Agile team.