Writing Concise Requirements

One of the ten big rules of writing a good MRD is writing concise requirements. We have to minimize the amount we write to avoid information overload. We also need to make sure we write enough to get the message across. How do we strike the balance?

The Big Rule of Brevity

From our previous article, Writing Good Requirements – Big Ten Rules:

Easy to read and understand. If only it were that easy. For whom is it easy to read? A market requirements document (MRD) is written for several different people on the team. It provides a vision of what problems our product solves. It provides clarification to the implementation team. It also sets expectations with stakeholders. Different people on the team have different domains of expertise – we have to write requirements that are easily understood by all of them.

The primary goal of concise writing is to improve communication and retention of ideas. The goal is not to save time. It takes more time to write less. Trust me on this.

How do we confirm effective communication?

Confirm Personally

The only way to confirm that the reader of a document understood what the author wrote is to ask him. “Did you understand?” doesn’t work. We have to create a feedback loop where the reader can give us confirmation that they understood. Teachers would do this in the essay portion of a literature exam – “In your own words, what did the author mean by…?”

We can get this feedback by directly speaking with the reader and using active listening skills to confirm that the reader understood the key concepts. The goal isn’t to correct the person’s understanding during the conversation. Rather, any misunderstanding is a “bug” in the documentation. We use those gaps to update our document, and then validate that the changes are understood.

Confirm Indirectly

A less effective technique, but one that might be required when working with a geographically distributed team is to infer levels of understanding by reviewing the output of the reader. We can potentially confirm that the reader understood the requirement by validating ‘the next step’ in the process. We can confirm that a business analyst understands the market requirement by validating the software specification that she creates. If the spec ‘completely covers’ the requirement, and does not introduce new ideas, then we know that the requirement was understood. If the spec is inadequate, then it may be due to mis-communication, or lack of competence.

As product managers, we aren’t in a position to validate the designs created by the implementation team, so this approach generally will not work for validating a spec. We may have the skills (perhaps we previously were developers or designers), but we should not try and do this – we risk getting caught in the weeds.

Improving Our Writing

• Requirements documents need to be scannable, much like web pages or articles. Readers need to be able to refer back to a particular requirement repeatedly to understand how to validate their work. We also need to be able to verify the requirement. Use of lists and short paragraphs help with referenceability and scanning.
• We have to be on the lookout for repetitive content within a requirement. The repetition at best is hard to read, and at worst is self-conflicting.
• We can include examples. Examples are often very illustrative of an idea.
• We can include OOA diagrams. Entity-relationship diagrams, when the reader knows how to interpret them, are very effective both for precise documentation, and for concise documentation. Remember that we are diagramming the problem, not the solution.

Conclusion

Write no more and no less that you have to. Confirm that the readers understand what you intend.