Documentation in Agile

We’ve all heard something about Documentation in Agile. I know I’ve heard some pretty extreme comments like “there is no documentation”. Well I’m here to set the record straight.

Let’s start by taking a look at the Agile Manifesto:

Agile Manifesto

Individuals and interactions over processes and tools

Working software over comprehensive documentation

Customer collaboration over contract negotiation

Responding to change over following a plan

That is, while there is value in the items on the right, we value the items on the left more.

As you can see it isn’t that there is no documentation, but rather we favor the delivery of “working software over comprehensive documentation”. So what does that mean, and why did I emphasize the word comprehensive?

If you are fairly new to working on software projects, you may not remember the days of huge requirements documents like I do. Projects started out with a group of analysts working together to create a requirements package over the course of several months. We would engage with the customer, run workshops, and watch what users did. We’d end up with one or more three-ring-binders full of documents. There would be statements like “the system must….” and “the system should….” We would give each line item a priority (High, Medium, and Low typically). Then we would create as-is process flows, to-be process flows, context diagrams, data flow diagrams, object models, and state transition diagrams to name a few. Each set of requirements were presented to and signed-off by the main stakeholders; and that may have been the last our stakeholders heard from the team until the software was ready for user testing. At the end of the project, the documents would end up on a shelf somewhere eventually being shipped off to long term storage, never to be seen again.

The Manifesto reminds us that no matter how much documentation we create, if we don’t produce working software, then we aren’t creating value for our stakeholders. It also reminds us to evaluate the documentation we do decide to create in order to ensure it is of value for the project.

The perceived lack of documentation in Agile environments isn’t just because of the manifesto, it is because everything we do is slightly different in Agile compared to a waterfall approach. We no longer create a load of requirements and toss them over the wall hoping the team will understand them enough to create a design document and code. Instead, we work together throughout each sprint to ensure we are creating value together by delivering working software together where everyone has complete understanding of user stories, and everyone is on the same page regarding the design as it emerges sprint by sprint. When specific documentation like Release Notes, or User Guides are required a user story is an acceptable way to track these documentation needs.

As the team discusses user stories in grooming sessions, the goal is to have each story fully understood by the team. The team may suggest other stories, or identify other items they need. The Product Owner and Scrum Master can work together to obtain documentation that is needed by the team to better understand the story. The team adds notes to the story to track decisions and comments that are made  keeping story documentation with the story. So what else might the team need? When working with a user interface, the team will likely need a wireframe or mock-up of the user interface. The team may also want an object model or database diagram. I’ve even known one developer that requested a State Diagram. Unfortunately, there is no single correct answer. The team or Product Owner, may need to engage with other teams (System, Database, or DevOps) to get the desired documentation ready for the team. For a great article on best practices in Lean/Agile documentation check out this article http://www.agilemodeling.com/essays/agileDocumentationBestPractices.htm

The three main artifacts in Scrum are the Product Backlog, User Stories, and Test Results. The Product Owner holds the key to understanding stakeholder needs. Should other documentation be required from a stakeholder or compliance perspective, a story in the backlog is a great way to address this need. Also as development occurs, the team needs to ensure that system decisions and their code are sufficiently documented so those supporting ,or enhancing the system in the future will be able to do so adequately. Consider including something in the Definition of Done (DoD) to ensure stories meet these non-functional needs.

Yes, documentation does exist when following an Agile Framework. However, we don’t create a document for the sake of saying we’ve done it. Make a conscious decision of what will be created, and what the intended use is. This way, you won’t have a library of out of date, never to be viewed again documentation.