Design Docs at Google

Google uses design docs as informal documents written before coding to define software designs. They record the high-level implementation strategy and the trade-offs behind key decisions, helping engineers solve problems early, build consensus, and keep cross-cutting concerns in view.

Reading notes

#

• Design docs are written before implementation and focus on the problem, the intended solution, and the trade-offs considered.
• The document can be more concise and easier to understand than code when the goal is to discuss a problem at a higher level.
• They help identify design issues early, align the organization, scale senior engineers’ knowledge, and preserve design decisions as organizational memory.
• A useful doc usually covers context and scope, goals and non-goals, the actual design, and alternatives considered.
• The design section should explain the chosen solution and why it best fits the goals under the given constraints.
• Useful material includes system-context diagrams, relevant APIs, data storage choices, and links to prototypes, while avoiding unnecessary verbosity.
• The shape of the doc depends on how constrained the solution space is, from greenfield projects to legacy systems with narrow options.
• Alternatives matter because they show why the selected design is preferable given the project goals.
• Cross-cutting concerns such as security, privacy, and observability should be addressed explicitly, often with dedicated reviews or separate docs.
• A design doc should be detailed enough to be useful but short enough for busy readers, with large projects often around 10 to 20 pages.
• A design doc may not be worth writing when the solution is obvious, the document becomes an implementation manual, or the overhead conflicts with rapid prototyping.
• The lifecycle includes creation and rapid iteration, review, implementation and iteration, and later maintenance and learning.
• Reviews can range from lightweight team feedback to formal meetings, and their main value is early incorporation of organizational experience.
• During implementation, the doc should be updated when the design changes, especially before the system ships.
• Older design docs remain useful as an entry point for understanding a system, even if they drift over time.
• Re-reading old design docs can help engineers see what they got right, what they got wrong, and how to improve future design decisions.