Design Docs for software architecture review

An intro to using Design Docs aka RFC’s to help teams build better software and share knowledge

Aug 6, 2022 3 min read

As software engineers our job is not to produce code per se, but rather to solve problems.

From Design Docs at Google

I love to say that “problems are good, we solve problems”. Part of solving a big problem is to clearly define it and then to outline a solution. This process can be formalized into a “Design Doc”.

Benefits of a Design Doc

Writing a Design Doc and having it reviewed does several things:

When to create a Design Doc, and when not to

Design Doc sections as bullets


Start of Design Doc template

Date: [YYYY-MM-DD]
Status: [Draft | In Review | Approved | Rejected]
Authors: [Your name, co-authors]

Context and scope

Problem Statement

[1-3 sentence description of the problem]


[1-2 paragraphs, giving more context than the problem statement]


[Short list of bullets, what’s in scope]


[Short list of bullets, what’s out of scope]



[Details on the chosen solution, including discussion of trade-offs]

System context diagram

[Diagram showing how this system fits into existing systems]


[Sketch of API endpoints with focus on parts relevant to this design and trade-offs]

Data storage

[Sketch of data storage with focus on parts relevant to this design and trade-offs]

Degree of constraint

[What aspects of the existing system constrain the design, or what boundaries are needed to help constrain it]

Alternatives considered

[Other possible solutions, discussing trade-offs that each design makes and how those trade-offs led to the proposed design]

Cross-cutting concerns


[What needs to be considered to keep systems secure]


[What needs to be considered to protect customers]



[Bullets to other docs and even Slack threads discussing the problem/solution]


[If useful to record notes, keep this free form section for notes as the document above takes shape]

End of Design Doc template

More references for Design Docs

Read more posts like this in the Software Engineering Toolbox collection.
Visit homepage
comments powered by Disqus