The Important Why

Most analysts understand that requirements and designs must be described in a form which allows developers to implement them. What they often fail to document, though, is the rationale behind the decisions. We should always remember that it is equally important to know why the stakeholders want something and why the feature was implemented this particular way.

"I think the most important things to document are the decisions. This goes for everything from requirements to architectural choices."

(from Stack Overflow)

It may not be evident right away, but not understanding the reasons blocks progress. When people do not know the motivations behind decisions, they are uncertain and are afraid to change things. This applies to high-level business goals as well as low-level functional requirements. The need to trace the rationale is important at all levels.

Documenting rationale is especially important in these cases:

  1. If something is labeled out of scope - describe why it is out of scope
  2. If something is available only under specific conditions - describe why particularly these conditions
  3. If something was changed - explain the decision which led to the change

Examples:

  • Payments via Paypal are available only for orders above $100. For developers, it is just another rule that controls the flow of the application. But the analyst is expected to be a partner to stakeholders, who sees around a corner and who can connect the dots. The ability to quickly answer "Why is Paypal limited to $100?" is crucial for this role.
  • "I've heard that it is no longer possible to pay via Paypal. How come?" This is a paradox, because here the analyst is not required to answer why something is implemented some way, but rather why something is no longer available. Although it does not make sense at first glance, it is a very common case. In general, it is beneficial to record not only why something was done, but also why something was not done.

ANTIPATTERN
If you want to make others angry, describe the rationale like this: "See the email conversation with Mike from 1st October 2015".
Always make it explicit without making readers search.