Effective Analysis and Documentation

The Important Why

Most analysts understand that, except for the simplest cases, the outcomes of analytical activities must be documented. This documentation captures what stakeholders want (requirements) and specifies how those requirements will be implemented technically (design documents). However, what analysts often omit is the rationale behind these choices. It is equally important to document why stakeholders want a feature and why the team decided to implement it a specific 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 might not seem obvious at first, but missing the underlying reasons for a decision can completely block progress. When people don't understand the motivation behind a requirement or design choice, they feel uncertain and are afraid to change things later. This applies to high-level business goals and low-level functional requirements alike. The need to capture this rationale is vital at every level.

Documenting the rationale is especially critical in these scenarios:

  1. If an item is marked out of scope – explain exactly why it was excluded.
  2. If a feature is available only under specific conditions – explain the reasoning behind those criteria.
  3. If a requirement or design has changed – explain the decision that led to the modification.

Examples:

  • Payments via PayPal are available only for orders over $100. For developers, this is just another business rule to implement in code. But an analyst is expected to be a true partner to stakeholders—someone who looks ahead and connects the dots. Being able to quickly answer "Why is PayPal limited to $100?" is a core part of the role.
  • "I heard it's no longer possible to pay via PayPal. Why is that?" This is an interesting paradox: the analyst isn't being asked why something was built, but rather why a feature was removed. While it might seem counterintuitive to document what is not there, it is a very common scenario. In general, it is highly beneficial to log both why something was done and why certain alternatives were rejected.

ANTI-PATTERN If you want to frustrate your team, write your rationale like this: "See the email conversation with Mike from October 1st, 2015."
Always state the reason explicitly within the documentation so readers don't have to hunt for it.