“Just enough documentation” in Agile: Possible practical approach

April 25, 2020

l

Victor Sapar

Agile encourages “just enough documentation”. The Agile Manifesto is clear about “working software over comprehensive documentation.” This is expounded further by one of the Agile principles: “The most efficient and effective method of conveying information to and within a development team is face-to-face conversation.”

But what is “just enough documentation” in practice?

Documentation is useful until you overdo it. Gathering any information not useful is a total waste of time.

That’s the main issue with typical software documentation that takes a lot of time to prepare yet most people don’t read. Just because it is a requirement and software development cannot possibly commence without it. That changed with Agile.

Documentation is useful until you overdo it. Gathering any information not useful is a total waste of time.
When new to Agile you will wonder just how it’s possible to start developing software without a requirements document. There is a misconception that Agile teams won’t write documentation at all.

There is no prescription on how to go about documentation in Agile. Agile principles serve as guide. They encourage developing practices that work in a team’s context.

The aim should be having enough information to keep everyone aligned, develop a common understanding and have reference to iterate with. Consistent with Agile, documentation should be incremental as well. You produce enough documentation to start with something then update when new information becomes available as a result of discovery and experimentation.

A Project Manager or Product Owner joining a team belatedly can face different challenges as far as software documentation is concerned. There can be working software with very minimal documentation that one of the first tasks will be to come up with a list of current features. Just to have an initial reference from which to start building a Product Backlog. On one hand, several months could have been spent revising a functional specifications document, process flowcharts or database schema without writing a single code.

What are practical examples of documentation for software development in Agile?

“Just enough” doesn’t always mean less or too simple. Any information created should serve a clear purpose towards enabling the team to produce working pieces of software.

In Scrum, an Agile practice, teams typically start with a Product Backlog, which is basically a list of user stories. A few references though are needed to inform a Product Backlog.

User tasks

Identify and list the tasks that users need to accomplish with the applications. Separate list by platform, e.g. mobile, web. Identify the core user tasks. These are the tasks that when accomplished either solve their problems or satisfy their needs. These are tied to the product’s value propositions.

User task flows

From the list of user tasks, visualize how each task can be accomplished. A diagramming app or a spreadsheet can be used for this purpose. The aim is to indicate the default sequence of steps to accomplish a certain task. Some user tasks may have more than one path to accomplish, e.g sign up with email address or using social account. When using a diagramming app, task flows are more usable when low-fi screens are used along with stencils.

User stories

With user tasks and task flows created, user stories can now be defined with their technical requirements and acceptance criteria. The user tasks become Epics. They fort part of the initial Product Backlog.

A Scrum team can begin iteration, i.e. first Sprint, as soon as the first few core user tasks have been identified and their corresponding task flows and user stories developed. These references then are updated as iterations continue.

Data flows

In some cases, data flows are necessary to better understand what user data are captured by the applications and how they are fed back to the users. These are normally created with the user tasks as basis. In one project, the team and I were able to clarify critical assumptions only after we created data flows. This resulted to significant change to the user task flows.

Questions and opportunities

A challenge in implementing Agile is capturing the outcomes of discoveries, experimentations and other insights that surface as the team moves from one iteration to another. A useful approach is to keep a “Questions and Opportunities” list. If using Trello, this can be the first column or list that can contain features or functions that are not yet ready to be considered in the Product Backlog as they require further discussion or research.The list may also include questions about assumptions which may impact the product design.

What about you? What is your experience in applying “just enough documentation” in Agile?

(Photo by Patrick Perkins on Unsplash.)

Sign up to the Monthly Newsletter

Share This