Day 5: Documenting Requirements

This chapter explains how to document requirements effectively by combining multiple notations—graphical models like BPMN/UML and natural language formats such as sentence templates—chosen pragmatically for their audience and purpose. It distinguishes artifacts (the deliverables that contain requirements) and shows how to build layered documentation, illustrated with a BPMN-based use case description, a state diagram for a “case ticket,” and a supplemental table that captures rules, timings, and step-level details without cluttering diagrams. Decision logic is extracted into decision tables to keep processes readable and configurable, while quality requirements and constraints (e.g., performance, security, evaluability, interfaces) are captured using sentence templates to make them precise and testable. Interface requirements are clarified through a high-level architecture model and a BPMN choreography diagram that focuses on inter-system message exchanges within the process. Finally, it demonstrates constructing a utility-analysis decision matrix to weigh custom development versus a standard product (favoring the standard product in the example) and stresses turning the rough concept into a high-quality RfP to reduce ambiguity and project risk.