Archive of Writing Articles

We ran a series called Writing Good Requirements – The Big Ten Rules in May 2006. Bloggers are notorious for not being able to count. We had ten rules at the time, and now we’re adding an eleventh. Writing Correct Requirements may have been the unwritten rule, but now we take a look at it.

The Monty Python troupe helps us remember five (no, three sir!) things about software requirements. And now for something completely different…

“Why?” The question is our inspiration and our muse. “Why?” is the justification for our requirements. The key to identifying “What?” and “When?”, which lead to “How?” and “How Much?” But there is another use for “Why?” – communication of intent (with stakeholders and implementers). Requirements documents are artifacts, but they are also dynamic documents. By documenting “Why?” a requirement is a requirement, we make it easier for future readers to understand.

Kathy Sierra writes (another) great article at Creating Passionate Users. This time, she talks about why users don’t upgrade and presents ways to get users to install the latest version. We focus in this article on one way in particular – using goal-driven documentation to encourage upgrading.

Yesterday we wrote about focusing our documentation on what our users are trying to accomplish. With a structured requirements approach, or with an interaction-design driven approach, we’ve already solved half the problem – determining what to document.

Why do we write documentation? Because someone told us to write it? Because our competitors have it? Or because we want our software to be easier to use? It should be the third one, but often, writing documentation is an afterthought, and it is deprioritized, and we just get it done, instead of thinking about the goals for doing it in the first place and doing it right.

Seilevel has a post that presents the top 10 signs that you should not pursue a career writing requirements, check it out. Thanks Joy for the great article!

One of the ten big rules of writing a good MRD is writing passionate requirements. What in the world is a passionate requirement [they were all wondering]? When you believe in the product, are committed to the work, and aren’t bored, you can write passionately. The goal of a requirement is to create sustained understanding. A dry document can create understanding, but an engaging document will sustain it.

One of the ten big rules of writing a good MRD is writing atomic requirements. Just as verifiable requirements must be concretely measurable as having been met or not, so must atomic requirements. If a requirement has multiple elements that can be implemented separately, it is not atomic.

One of the ten big rules of writing a good MRD is writing verifiable requirements. Verification is both a function of having a precise goal, and having the ability to affordably measure the requirement. A precise goal is a verifiable requirement if we can clearly answer “yes” or “no” when asked if the requirement has been implemented. We also face the practical realities of being able to measure the results profitably.