NVISIA - Shorter Requirements are Better

Our Tech Blog

Shorter Requirements are Better

When writing requirements documents, it’s tempting to add more & more details and create longer documents in order to make sure that the requirements are perfectly clear. But often this doesn’t help; instead, the best way to make sure your requirements are understood clearly is to make the document shorter. The extra details can mislead and confuse the reader if they are not essential. It’s better to take the time to make your document shorter and clearer to get your meaning across.

The key to creating documents that do not include any unnecessary words and convey exactly what you mean is writing at least two versions of your document. In the first draft don’t worry about including too much. At this time the most important thing is to include as much information as you can. After you have a first draft that’s too long, you can edit and rearrange the document to remove redundant sections and include only what is necessary, with the most important ideas clearly identified.

There’s a great book called Revising Prose that describes an 8-step method for this revision process. The steps are straightforward and easy to do–step 1 is “Circle the prepositions.” It really works, and the book includes lots of good before & after examples demonstrating the process. The book covers any type of writing, not technical or business writing in particular. Because the focus is on making the action of each sentence clear, rather than strings of modifiers, it is very applicable to requirements documentation.

Now if you’re creating user stories and follow the standard story template there won’t be anything to revise. But with use cases and functional specifications there is usually an opportunity to make your sentences clearer and get rid of information that isn’t necessary. Product vision documents and business cases are perfect candidates for the revision process.