Writing Design Docs That Get Read

Effective design docs serve as a critical tool in software engineering for achieving project alignment and improving engineering outcomes by clearly communicating a high-level solution to a problem. Their primary goal is to ensure all engineering teams are on the same page quickly, facilitating decision-making and outlining trade-offs without necessarily documenting every minute detail. While templates like those used at Google can provide structure, the focus remains on conciseness and readability to ensure busy professionals actually engage with the technical documentation.

The Core Purpose of Design Docs

Design documents, often appearing as RFCs (Request for Comments) in software engineering, serve as a foundational tool for engineering teams to align on the "what" and "why" behind a proposed solution before significant code is written. Their primary benefit is to foster organizational consensus around design choices, thereby reducing rework and creating a clear record of decisions. For instance, at Google, while reviews aren't strictly required until project launch, engaging privacy and security teams early through design docs ensures these considerations are baked in from the ground up. This proactive approach prevents costly retrofitting.

The decision to write a design doc hinges on the ambiguity of the design problem, whether due to problem complexity, solution complexity, or both. If a solution is straightforward and unambiguous, the overhead of creating a design doc might outweigh its benefits. However, for projects with meaningful trade-offs or intricate system design, these documents become critical. They provide a high-level solution detailed enough for an experienced coder to implement without making significant architectural decisions. This clarity is crucial for maintaining project alignment across various engineering teams, ensuring everyone operates from the same understanding of the problem and the proposed approach.

When to Write (and Not Write) a Design Doc

The decision to write a design doc hinges on whether the solution to a design problem is ambiguous, either due to problem complexity, solution complexity, or both. If a solution is straightforward, such as creating a simple CRUD endpoint that aligns with existing codebase patterns, the overhead of a design doc might not be justified. For instance, moving code from one file to another for refactoring a codebase typically doesn't warrant a full design document.

Conversely, design docs are crucial when there is significant ambiguity, complexity, or meaningful trade-offs to consider. This includes projects involving intricate system design or those requiring detailed architecture diagrams. If a project involves substantial decision-making, such as new feature development impacting multiple engineering teams or requiring input from privacy and security teams, a design doc ensures alignment and documents the rationale behind choices. These documents act as a high-level solution guide, enabling an experienced coder to implement the project without making significant architectural decisions independently. When in doubt, it is often better to draft a design doc to avoid potential rework and ensure project alignment.

Essential Components of an Effective Design Doc

A robust design document provides a complete, high-level solution detailed enough for an experienced developer to implement without significant architectural decisions. Key structural elements ensure clarity and alignment:

• Problem Statement: Clearly defines the issue the design aims to solve. This sets the context and purpose for the entire document.
• Goals and Non-Goals: Specifies what the proposed solution will achieve and, equally important, what it will not address. This manages expectations and scopes the project.
• Proposed Solution: Outlines the core design, including architecture diagrams where appropriate, to illustrate how the system will function. This section should be detailed enough to guide implementation.
• Alternatives Considered: Discusses other approaches that were evaluated, demonstrating thoroughness in decision-making. This section is crucial for understanding trade-offs.
• Rationale and Decisions: Explains why the chosen solution was selected over alternatives, detailing the reasoning behind key decisions and trade-offs. This provides a clear record for future reference and review.
• Open Questions/Future Work: Identifies areas that still require further investigation or are deferred for later phases.

These components ensure that the technical documentation facilitates project alignment across engineering teams and supports informed decision-making.

Crafting Readable and Concise Design Docs

Effective design docs prioritize clarity and brevity to ensure they are actually read by busy engineering teams. A common pitfall is creating documents that are excessively long, such as 20-page Google Docs, which tend to go unread. The ideal length for a larger project's design doc is typically 10-20 pages. For smaller, incremental improvements or sub-tasks in an agile project, a "mini design doc" of 1-3 pages can be sufficient, maintaining focus on a limited problem set while still following the core steps of a longer document.

To achieve conciseness, focus on the "what" and "why" rather than becoming an implementation manual. Design docs should explain the rationale behind decisions and trade-offs, not simply dictate "how we are going to implement it." One method to improve conciseness is to adopt a "cut with a red pen" approach, writing, crossing out, and rewriting to use as few words as possible to communicate ideas clearly. This skill, often taught in technical writing courses, emphasizes summarizing and becomes easier with practice. While an LLM can help structure initial thoughts, the ultimate goal is to order your ideas for maximum readability. Remember, the primary objective is to get everyone on the same page quickly, not to document every single detail.

Streamlining the Design Doc Process

Improving the speed and efficiency of writing design docs involves leveraging existing structures and optimizing the feedback loop. One effective method is to start with a design doc template, such as the one used by Oppia, which ensures all necessary information is documented in a central location and facilitates effective project reviews. Instead of starting from scratch, make a copy of a template and fill in the sections, proofreading before sharing for review.

The review process itself can be streamlined by treating comments similarly to a code review. When responding to reviewer comments, reply to each one (e.g., with "Done") and update the document, but do not resolve the comment thread. This allows the reviewer to track addressed comments and determine if further follow-up is needed. For initial drafting, a "brain dump" into a document, potentially using dictation, can quickly capture thoughts. An LLM can then help structure and organize these initial ideas for readability, even if the output is later refined manually. This iterative approach, combined with templates and structured feedback, helps accelerate the creation of clear and concise technical documentation.

Frequently Asked Questions

Conclusion

By leveraging templates, streamlining the review process, and focusing on clarity, you can create design documents that are not only comprehensive but also highly readable and effective. This approach ensures that your technical solutions are well-understood, fostering better collaboration and successful project outcomes. Ultimately, a well-crafted design doc serves as a vital communication tool, bridging the gap between complex ideas and actionable plans.

Sources & References

• How to get faster at writing design docs and drafting diagrams - Reddit
• Design Docs at Google - Industrial Empathy
• Writing Better Design Docs - by drmorr - Applied Computing Research Labs
• Why I Write Design Docs 5x Faster Than Before (And Still Get Them ...
• Writing Better RFCs and Design Docs - DEV Community
• Writing a good design document - Hacker News
• Documentation | Design good practices
• How to Write a Design Document
• Writing design docs · oppia/oppia Wiki · GitHub
• How to Write Design Documents That Actually Help You ...