Developing Software on a Beer Mat

by Ann-Cathrin Mackenthun on September 25, 2012

In agile software development we no longer create lengthy functional specifications or product requirements. We write our requirements as short user stories that could easily fit on a note card or a beer mat. Software requirements on a beer mat? How can they possibly make sense to the developer or the technical writer?

Scrum, Sprints, Increments

A user story briefly describes what the user needs, let's say a new print button. Agile development methods like Scrum employ these user stories. A Scrum project is not planned from beginning to end. The developers work in short development cycles, so-called Sprints. During each Sprint, small and self-contained functions (increments), the new print button, for example, are developed. Each increment comes with all the necessary components, such as the database access, the functional code, and the user interface. So at the end of each Sprint, the software could theoretically be released with its new functionality.

User Stories

Compared with traditional developing methods, Scrum takes an entirely different approach. When defining requirements, Scrum focusses on the user. The user story provides the developer with the answers to the most vital questions: Who needs which function and why? In our print button example the user story could read like: "As a lab employee I want to print the graph of the test result 3aXX directly from the graphical dialog."

Cryptic Notes

In the daily routine of developing software, information sometimes gets lost. We all know this situation: "Joe will work on it; he knows what is meant here."

Or: The team writes a note of a requested implementation that looks like this: "From Graf_008erg implement print_graf". But the feature cannot be implemented right away. The software, however, changes with each Sprint. After a few weeks have passed, no one remembers what this cryptic note means.

If you want to avoid this, use a few simple tricks.

Write Good User Stories

In a first step you can apply Mike Cohn's (MC) formula: As [who] I want [what] so that I can [why]. The three W's can easily be replaced. The exact form doesn't matter. Important is that all the information is included.

More detailed are Bill Wake's (BW) requirements INVEST criteria:

I – Independent: Is the requirement self-contained and independent from other requirements?

N – Negotiable: As the developer of the software do I know what the user really needs? Can I negotiate different solutions for implementing the requirement?

V – Valuable: Is this function important? Does it have any business value?

E – Estimatable: Can I estimate how long it takes to develop this feature? Will it take less than two days?

S – Small: Is this requirement really the smallest increment or could I divide it into even smaller increments?

T – Testable: Can I test the implementation? And do I need more information to find out what exactly is the subject of the testing?

From a Beer Mat to a Manual

How do technical writers benefit from these user stories? Because the stories themselves assemble a task-oriented manual. It is immediately obvious to which manual a new function belongs. For example, above mentioned print function would be placed in the lab manual. Furthermore, the printing of the graph is part of the user story and can be put as an activity into the right chapter. And if there is an explanation in another chapter of how to do the testing of 3aXX, the technical writer inserts a reference to the chapter that describes the printing option. Writing manuals was never simpler.

Benefits for Documentation and Development

With a well written user story both the developer and the technical communicator benefit. The developer implements functions that the user actually needs. The technical writer benefits from the task-oriented description in the user story. If you know the processes in an agile software development project, you can deliberately access all required information. And who knows? You might even be interested in helping write good user stories. After all, understanding the user and being precise is what we do best.