Navigating the Landscape of Formal Design Documentation
In software engineering, especially as projects scale in complexity and team size, winging it with a bespoke design structure is a recipe for disaster. Precise, agreed-upon blueprints are essential for guiding development, ensuring consistency, and facilitating long-term maintenance.
While many teams thrive on lighter-weight documentation such as ADRs, some scenarios demand a more rigorous approach. Today, we'll explore two prominent types of formal design documents: Architectural Descriptions (ADs), often guided by standards like ISO/IEC/IEEE 42010, and Requests for Comments (RFCs), famously used by the Internet Engineering Task Force (IETF). Understanding their purpose, structure, and nuances can help you choose the right tool for your architectural challenges.
What is an Architectural Description?
An Architectural Description is a comprehensive document or set of artifacts that captures the architecture of a software-intensive system. Its introduction typically frames it as a formal architecture description. The standard ISO/IEC/IEEE 42010 (which superseded the earlier IEEE Std 1471:2000, its origin) provides a framework for creating, analyzing, and sustaining ADs.
ADs are inherently formal. Here are some factors that favor the formality of ADs.
- The project impacts many teams and requires a shared, unambiguous understanding.
- The consequences of mistakes are grave enough to justify the costs of a larger and deeper review by many engineers from different experience levels. The thoroughness helps catch potential issues early.
AD Anatomy
A robust AD template typically includes the following sections.
Introduction: Overview, scope, and goals of the architecture.
Stakeholders and Concerns: Identifying who cares about the system and what their key interests or worries are (e.g., performance for users, maintainability for developers, security for compliance officers).
Viewpoints: Prescribed ways of looking at the system to address specific stakeholder concerns. Each viewpoint defines the conventions for constructing and using a view.
Views: Representations of the system from a particular viewpoint (e.g., a logical view, a deployment view, a process view).
Consistency and Correspondences: Rules and relationships ensure that different views are consistent.
Decisions and Rationale: Document key architectural decisions and their reasons, including alternatives considered.
Arguments For ADs
Attention to detail: With an AD, you are less likely to overlook important details. The structured approach comprehensively considers various aspects and stakeholder needs, making it easier to notice inconsistencies or conflicting requirements.
Arguments Against ADs
Resource-intensive: AD takes a long time and involves more people. The rigor and detail demand significant effort and collaboration.
Disposable code: The level of detail and amount of resources required for an AD is such that you might want to code up a Proof-of-Concept (PoC) along with the AD. This PoC will most likely not survive the review process so it will end up being thrown away which could be viewed as a waste of time.
Methodology gap: Engineering teams started using AD when waterfall was the most predominant project management methodology. Extensive upfront documentation might feel disconnected from agile coding practices.
Review confusion: An AD is either a living document or a snapshot in time. A living AD is updated as the architecture evolves. Each update triggers a new review cycle, which can increase the scope of the change. What should happen if a reviewer suggests a change for a part of the AD that was not changed?
What is a Request for Comments?
As mentioned earlier, the IETF initially introduced the RFC as a document that describes methods, behaviors, research, or innovations applicable to the workings of the Internet and Internet-connected systems. The introduction of an RFC often literally signifies a request for comments from the broader technical community. Its origin lies in defining Internet standards.
RFCs are suitable when:
- The scope is broad, often proposing new standards, protocols, or significant architectural patterns.
- A high-level perspective is needed, though this can drill down into specifics.
- The design impacts many teams and even external organizations.
- Due to its potential widespread impact, it requires a larger and deeper review from more senior engineers or subject matter experts.
RFC Anatomy
A typical IETF template for an RFC includes the following sections.
Introduction: Problem statement, proposed solution's scope, and goals.
Requirements: The proposal aims to meet key requirements (often using terms like MUST, SHOULD, and MAY see RFC 2119 for more information).
Body: The core technical specification, often detailed with diagrams and figures.
Security Considerations: A dedicated section addressing potential security implications.
Appendix: Supplementary information, acknowledgments, or further details.
Arguments For RFCs
Encourages long-term thinking: The RFC process produces robust, well-vetted specifications for longevity and broad adoption.
Arguments Against RFCs
Takes a long time and involves more people: The community review and consensus-building process can be lengthy.
Hard to future-proof: Despite best efforts, predicting all future needs and technological shifts is challenging, making some aspects potentially difficult to adapt later.
AD vs. RFC: Choosing Your Approach
Both ADs and RFCs represent significant investments in formal design.
ADs are typically inward-facing, focusing on defining and communicating the architecture of a specific system to its internal stakeholders. They emphasize multiple views to satisfy diverse concerns.
RFCs are often more outward-facing (or for large internal "platform" efforts), aiming to propose, define, and standardize protocols, interfaces, or architectural patterns for broader use. They invite wide scrutiny.
You can also mix smaller documents of various types. Here is an example: Consider proposing a new platform capability. Start with an RFC to capture technical requirements. Introduce an AD snapshot for the initial system design meeting those requirements. Capture future evolution through a series of ADRs.
Feeling Overwhelmed by Design Documentation?
Choosing the right level of design documentation can be a complex decision. Too little, and you risk chaos; too much, and you risk stagnation. If you're struggling to define your architectural processes or select the appropriate documentation strategy for your projects, I can help. With experience across various scales of software development, I can assist your team in:
- Understanding when and how to apply formal design documentation like ADs or RFC-style proposals.
- Tailoring documentation practices to fit your team's culture and project needs.
- Establishing effective architectural review processes.