Telling Stories: A Short Path to Writing Better Software Requirements

Chapter 2. The Language of Your Story

So far I've avoided the most difficult point: how to write. Of course I cannot explain how to write well in this book. I can only describe some qualities of good writing that are especially important to writing requirements and recommend some other resources. I do hope I can at least inspire some hope and make a few simple suggestions.

The language of requirements must be clear and precise to all potential readers. It must define a specific, measurable outcome.

How to do this? The answer involves learning a bit about writing. As a rarely taught subject, software writing is overly mystified by those who haven't done it much. It is difficult to write beautifully, but it's not that hard to be clear. Writing is more like playing guitar than violin. After only a few lessons, most people can play a few simple songs, have fun, and get a point across playing the guitar. Most beginners sound terrible on the violin for several years.

If you don't try anything too fancy in writing, you can usually get your point across and be clear, even convincing, without being a virtuoso. Most bad writers get into trouble because they try to do too much and quickly strangle the meaning of their work.

Clarity, brevity, and precision are vital qualities of effective requirements writing. Let's consider these concepts.

Clarity

Clarity is not a divine gift that some have and some don't. True, some writers are exceptionally clear and others struggle to be barely comprehensible. ...