A Picture Is Worth A Thousand Requirements

Object oriented analysis and design (OOA/OOD) is a technique used to gather requirements and develop software, as an alternative to more traditional text-based techniques.

OOA allows for clarity of communication, by creating descriptive and unambiguous documentation of requirements. It comes with a great big giant caveat – the consumers of the requirement need to know UML. This is usually not a problem for development teams, however stakeholders are also consumers of requirements – they have to validate that what you’ve documented expresses what they require. Without a tech-savvy stakeholder, this approach is unlikely to provide unambiguous documentation.

Here’s a simple example describing the requirements for managing orders.

In prose, we could also capture the same information as follows:

1. The system shall include a representation of customer orders.
2. Each order will have a single associated customer, and each customer can have multiple orders. Note that a customer is not required to have any orders.
3. Each order will have at least one, and possibly multiple line items. Each line item is uniquely associated with a single order.
4. Each line item represents a single product. Note that a product is not required to be represented in a line item. A product can be represented in multiple line items (even within the same quote).

OOA is compellingly powerful as a descriptive tool – it took less time to draw the diagram, and it can be easier to read than the prose. There are, however, downsides to incorporating this approach into a traditional project.

• Requirements are combined into a single entity. It is important to treat requirements atomically – in approval, scoping, scheduling, and delivery. There is a risk that the team delivers part of a diagram (say the above was implemented, except orders can only contain one line item). As the size of a diagram grows, the risk of this increases. We reach a point where information density becomes a detriment and not an asset
• As we pointed out, every consumer of the requirements needs to know how to read UML – to know that composition is reflected with the black diamond, and association with an arrowhead, and everything else.
• Since an OOA diagram looks very much like a good OOD diagram, we run the risk of talking about the implementation in the requirements. It’s imperative that we only document the expression of business requirements, not implementation approaches.
• Diagrams also run the risk of creating map shock – where a reader is cognitively overwhelmed by the sudden introduction of a large amount of complex data represented spatially. Thanks Cliff Atkinson for doing and posting the interview we referenced.

Proponents of OOA argue that the diagrams are not intended to stand on their own – that there is a notion of “accompanying prose” that must be included. When I took a training class on applying OOA/OOD to software development, unfortunately, our instructor waived his hands at the textual portion.

Combining the two techniques can provide striking clarity in a requirements process. The collaborative generation of the diagram can be one of the most powerful elicitation techniques when both gathering requirements and validating them for correctness and completeness. They also can serve as a great high level overview that will help the development team in their architectural design work (the OOD part).

By using composition in requirements, we can manage the details in the text-list, as cohesive components of a high level concept represented as a drawing. Be careful not to express the diagram as the requirement (it would be redundant) – include it as a reference associated with the high-level requirement.