Comprehensibility vs. Precision by Bruce Nielson
Abstraction vs. Precision in Requirements
I used to be an instructor for Rational Software’s RequisitePro software, which included a class called “Requirements College.” This useful class helped teach people how to elicit requirements from their customers.
Three things that really stuck with me from the class were, first, the idea that one does not “gather requirements’ per se, but elicits them. If taken literally, “gathering requirements” implies that requirements are readily available and you just have to pick them up and take them. This flies in the face of reality; requirements have to be created from nothing.
The second was the idea that How and What are relative to a point of view. I’ve written about this in the past.
The third was that, according to the course, abstraction and precision form a spectrum that affects comprehensibility. The idea was that if you are too abstract, your writing won’t be comprehensible at all. But if you are too precise, it’s also not comprehensible. The following graph illustrates the idea:
Legalese is a good example of this. Legalese is very precise wording for legal purposes, but because its so precise, it’s difficult for anyone but a lawyer to understand – and that’s not a fair comparison because the lawyer at least gets paid to slog through it.
Therefore, according to the course, requirements should seek the sweet spot of maximum comprehensibility, where it’s neither too precise nor too abstract.
Useful, but Misleading
This idea of avoiding too much precision to increase comprehensibility is a useful idea. But I couldn’t help but feel it also somewhat mislead.
I kept thinking to myself: but what if that level of precision is what you need to come to an agreement on?
Imagine dumbing down legalese so that it’s more “comprehensible.” Would that be a good thing? It’s not like legalese was created to keep lawyers employed (though sometimes it might seem that way.) On the contrary, legalese was created because a more comprehensible abstraction would also have multiple possible meanings. In a court of law, that’s precisely what we’re trying to avoid. Ergo, the need for legalese.
Are Software Requirements Like Legalese?
Now if the point of requirements documents is to get everyone going in the same general fuzzy direction, I can see that a comprehensible abstraction would be the best way to handle it.
But if the point of the requirements is to come to agreement on how to specifically implement something, there is no substitute for precision in details. I believe “requirements” (and also “design”) must therefore be considered as something closer to legalese in such a circumstance.
In an ideal world, we’d probably want both. We’d want to start at the highest level of abstraction and work our way down, keeping every stakeholder informed and involved as we take the fuzzy abstraction and turn it into something specific and detailed.
But in reality, the Marketing People drop out after the first details start to be filled in, Management’s eyes begin to glaze over once the “requirements document” is complete, and even the Technical Lead might to nod off once we get into the really nitty gritty details.
Conclusions
I see an essential tension between “comprehensibility” and the need to come to agreement on an actual implementation, which requires comprehending the actual details. I think this is one of the hardest problems in software development and I do not expect this to be a problem that can ever be overcome because it’s the essential nature of software itself.