Decision Documents

Design documents and reviews are meant to minimize technical and architectural debt across projects and teams. They do so by making design decisions and processes visible and accessible, and by fostering increased standardization around approach and quality. This document discusses three types of documentation:

• Architecture Decision Records (ADRs),
• Design Documents (Design Docs), and
• Requests for Comment (RFCs).

Each is a form of change documentation that's best suited for the role it serves in the development process.

It's very simple to get started:

1. Plan before making code changes
2. Capture the plan in a written document
3. Seek review and approval

Aspirationally, a good design documentation and review process would also:

• Send the design document to all engineers in the department
• Require the above steps for all engineers and projects

Besides the original documentation of a software design, design docs fulfill the following functions in the software development lifecycle:

• Early identification of design issues when making changes is still cheap.
• Achieving consensus around a design in the organization.
• Ensuring consideration of cross-cutting concerns.
• Scaling knowledge of senior engineers into the organization.
• Form the basis of an organizational memory around design decisions.
• Acts as a summary artifact in the technical portfolio of the software designer(s).