On a painfully cold night in February, not long ago, I rounded up several friends and headed down to a slightly moldy church basement on R Street. The plan was to prepare a meal for a nearby women’s shelter. Our enthusiasm ran high; our skill and organization, perhaps not quite as high.
Fortunately at least one person had prepared.
An elderly Carmelite Sister had written, in cheerful ballpoint lettering on what might have been dot matrix printer paper, a numbered list of exactly what we had to do to provide a pleasant evening for forty women and children.
She thought of everything. There was a precise list of recipe requirements, of course, each step positioned on a different line, with clear acceptance criteria (“when the cheese has toasted scabs about the size of a quarter, it’s done”). She’d drawn a tiny map of the kitchen cupboards, arrows pointing out the relevant areas.
She included notes on the constraints of the old gas oven range and the capabilities of the dining area in the shelter. She even defined her terms to avoid ambiguity, betting that none of the six volunteers under 25 ever referred to margarine as “oleo”. We tacked her document to the kitchen wall and carried out her orders with great success.
She wrote those instructions with human beings in mind, and designed them specifically to help real people accomplish real goals.
On a recent project, I spent several hours writing requirements for a process that involved many decision points. I became rather bogged down trying to technically portray every possible combination of events that might occur from every angle of symmetry. I ended up with convoluted sentences that included redundancies and outlandish exception cases, all of which did not effectively communicate the goals of the process.
It wasn’t until I took a step back to consider both the perspectives of (1) the person reading and trying to implement these requirements and (2) the person who would eventually use this process to accomplish a task that I could pare my writing into concise and necessary statements.
We do not write requirements in a vacuum; they aren’t an exercise in logic and grammar. We’re trying to communicate to an actual person, to help her do her job more efficiently. It may be helpful to stop every once in a while and consider the needs of the human being reading the instructions and trying to make lasagna.
