Wednesday, 11 July 2018

Why are textual activity diagrams good for creating requirements from use cases?

One successful approach is to use one activity diagram per use case to document the steps of the use case, together with trigger, pre-conditions and post-conditions.

The benefits of the activity diagram are:
  1. Their flow-chart like syntax can be read with little or no training. This makes them the most easily consumable behavioural diagrams in UML and SysML and hence a good place to start engagement with stakeholders (caveat: stick to using control flow semantics). 
  2. Alternate flows of the use case can be expanded on the same canvas (either using interruptible regions or decision nodes) giving the diagram a power of analysis that is difficult with textual step-based approaches. “If you don’t actively attack the risks, the risks will actively attack you.” Tom Gilb, 1988

Importantly, using a model, until a Word document we can easily capture traceability between use case steps and textual requirements using SysML relations (satisfy, refine, and other dependencies). From the activity diagram we might create textual requirements. The activity diagram is the canvas in which we reconcile textual system requirements with the steps of a use case. They provide complementary views of the system from an external perspective.

Traceability in-situ has significant benefits, including:
  1. Increased ability to cope with requirements churn. When developing new ideas requirements churn cannot be ignored. When performing requirements definition work churn is both a good thing (we honed down the ideas to distil then into the essence of need) and a bad thing (if we can't cope with changes). Capturing traceability in-situ as part of the task makes it virtually effortless, whereas waiting until after the event makes it virtually impossible.
  2. Increased audit-ability and assurance of due diligence. This is necessary for safety-related processes such as ISO 26262 or for general process compliance to standards such as A-SPICE.
  3. Improved reviews. Requirements can be written so they are SMART (Specific Measurable Achievable, etc) but we have a picture of the story of a use case to put and read them in context, making the requirements review easier and more pleasurable (focusing not on the English grammar but more on the user experience).
In A-SPICE this relates to:

SYS.1.BP1: Obtain stakeholder requirements and requests. Obtain and define stakeholder requirements and requests through direct solicitation of customer input and through review of customer business proposals (where relevant), target operating and hardware environment,
and other documents bearing on customer requirements. [OUTCOME 1, 4]

SYS.1.BP2: Understand stakeholder expectations. Ensure that both supplier and customer understand each requirement in the same way. [OUTCOME 2]

NOTE 4: Reviewing the requirements and requests with the customer supports
a better understanding of customer needs and expectations. 

Traceability relates to:

SYS.1.BP5: Manage stakeholder requirements changes. Manage all changes made to the stakeholder requirements against the stakeholder requirements baseline to ensure enhancements resulting from changing technology and stakeholder needs are identified and that those who are affected by the changes are able to assess the impact and risks and initiate appropriate change control and mitigation actions. [OUTCOME 3, 6] NOTE 5: Requirements change may arise from different sources as for instance changing technology and stakeholder needs, legal constraints.