The 300-Page Document Nobody Reads
A public benefits agency is procuring a new case-management system. Fourteen stakeholders are involved: three business representatives, two security auditors, four developers, two operations engineers, two supplier architects and one data protection officer. The existing architecture description is a 312-page Word document last updated 14 months ago with 40 Visio diagrams, no version control and no clear owners. A new supplier needs eight weeks to understand the integration landscape; developers ask the architect in chat instead of reading the document; terms drift ('caseworker portal' and 'citizen portal' are used for the same component). An audit in three months requires traceability from requirements to architecture elements. Integrations with three legacy systems change every quarter; the core domain changes rarely.
1. Which architecture views and additional artifacts would you produce, and for which stakeholder? Justify by the questions each answers.
Read the worked answer
Select views by stakeholder question and rate of change.
- Context view: the case-management system, citizens, caseworkers, three legacy systems and the two suppliers. For business representatives, auditors and supplier architects; answers scope and external dependencies. This is the one view almost everyone needs.
- Building-block view, coarse: major components and responsibilities, not classes. For developers and supplier architects; answers 'what are the parts and who owns them?'
- Runtime view: the critical case-handling and integration flows, including legacy failures. For developers and operations; answers 'how does it behave at runtime and where are the timeouts?'
- Deployment view: nodes, environments, network zones and data stores. For operations and security auditors; answers 'where does it run and what crosses trust boundaries?'
- Data view and retention map: personal data, audit data and retention rules. For the data protection officer and auditors; answers lawful handling and deletion.
- Interface catalogue: legacy and supplier interfaces, versions and SLAs. For supplier architects and developers; answers integration contracts.
- Decision log and glossary: why structures exist and what terms mean. For all; the glossary resolves 'caseworker portal' versus 'citizen portal'.
- Traceability matrix: requirements to architecture elements and tests. For the audit; answers coverage and impact.
Forty diagrams are not a communication strategy. A small, owned, versioned set with clear questions is more useful than a large document with no owner.
2. How would you communicate and govern this so the document does not rot again? Include formats, ownership and review cadence.
Read the worked answer
Treat the architecture description as a maintained product, not a one-off deliverable.
- Single source of truth: move the description into a version-controlled repository or architecture tool. Store diagrams as text or model files where practical so changes are reviewable. Retire the 312-page Word file explicitly to avoid two truths.
- Small views, clear owners: each view has an owner and a last-reviewed date. The architect owns cross-cutting views; operations owns deployment; security owns trust boundaries; suppliers contribute interface descriptions under review.
- Docs-as-code workflow: architecture changes go through the same pull-request or review path as code. A change that affects an interface or quality scenario requires updating the relevant view and decision record.
- Cadence: monthly review of decisions and interfaces; quarterly review of views that change (integrations); annual or event-driven review of stable core views.
- Audience-specific communication: a one-hour context and integration briefing for business and suppliers; a developer onboarding pack with building-block and runtime views; an audit pack with traceability and data retention; a glossary in every pack.
- Definition of done: 'architecture description updated' is part of the change, not a separate project.
The reasoning: the current document fails because it has no owner, no change path and no audience-specific entry point. Governance should make the useful path the easy path, not add a quarterly approval ritual.
3. What should be done about the terminology drift and the audit traceability requirement?
Read the worked answer
Fix terminology before it contaminates requirements and contracts.
Glossary: create a canonical term list with definitions, aliases and forbidden synonyms. For example, define the citizen-facing component and the caseworker-facing component separately, and map 'citizen portal' and 'caseworker portal' to their canonical names. Assign an owner, publish it with the architecture description and use it in interface names, diagrams and requirements. Review new terms at the monthly architecture review.
Traceability: assign stable identifiers to requirements and architecture elements. Maintain links in a tool or a version-controlled table: requirement to context element, building block, interface and test. Do not attempt to trace every sentence; trace the significant requirements, including audit, retention, availability and access control. Sample-check the links with auditors before the audit and record gaps as risks.
The two concerns connect: if 'portal' means different things in requirements and diagrams, traceability is formally present but semantically wrong. A glossary plus a small, maintained trace matrix is more credible than a large document with ambiguous links.