Archive of Writing Articles

Pragmatic Marketing has a training seminar called Requirements That Work. In support of that, they provide a list of 8 characteristics of good requirements. We change one and add two more to round it out to The Big Ten Rules. Combine this with Michael’s ten tips for writing MRDs, and we’ve got a good handle on how to create a great MRD.

Michael has posted five (plus five) tips on writing a market requirements document (MRD). Michael has written a good set of tips with detailed explanations and anecdotes. We have re-organized these tips into three general areas of guidance and provide our thoughts.

…Is another man’s treasure. There are many different ways to document requirements when developing software. And there is a proliferation of requirements documents - MRD, PRD, SRS, FRS and design documents. Everyone has a perspective on what each document represents, and each person on the team has a unique perspective on what questions the document answers.

We’ve posted tips about targeted communication - tailoring the message for the audience. Anthony Mersino has an excellent post from January of this year about how to write a good status report. He provides seven excellent guidelines for status reporting, and all of them around providing the message our audience cares about, as effectively as possible.

Most guides to writing an executive summary miss the key point: The job of the executive summary is to sell, not to describe.

This from Guy Kawasaki’s recent post, The Art of the Executive Summary. Guy’s article is structured towards pitching an idea to a potential investor. We’re going to apply the same rationale to the communication that is key to successful product development - communication from the team, to stakeholders and sponsors.We also communicate with people outside of our team. We communicate to set expectations with customers, users, and clients.We communicate with sponsors, customers, and others who fund our software development. Without these channels of strategic communication, we won’t have a project, or worse, won’t have a customer when we’re done. External communication is strategic communication.

This video showing the abuse of jargon (2 minutes) is absolutely hysterical, and should be watched for humor alone. However, it also drives the point home about the effects of using jargon when writing requirements.
When we write a PRD or SRS if we use the jargon of one domain, this is what we will [...]

Writing requirements without ambiguity

This is one of the harder parts of writing good requirements. Marcus tells us to avoid it with a good example here. Jerry Aubin at Seilevel has written an outstanding post on the subject, The art and science of disambiguation. Jerry starts his post with a gripping example from Weinberg and Gause:

Background:

In our previous post, Sample use case examples, we created two informal use cases. The use cases were written to support product requirements defined as part of a project to reduce test suite maintenace costs. In this post, we will define functional requirements that support these use cases. This process is an example of using structured requirements, applied to a small real world project.

Learn from an early mistake of mine
At a previous employer, the first time I played the role of requirements manager (technically, program manager - with responsibility for the functional spec), I made a bunch of mistakes - this post is about one of them.
The setup
We were engaged in a high-pressure, tight-deadline, under-staffed project with a [...]

Too many companies don’t document their requirements.

Worse still, too many companies over-document their requirements.