A design doc (also called a technical design document or TDD) is a written artifact that describes a proposed software system, feature, or architectural change before implementation begins. It serves as a communication and alignment tool for engineers, product managers, and stakeholders.
A design doc is a structured written document that captures the problem being solved, the proposed solution, and the key decisions made along the way. It is written before code is committed, acting as a blueprint for implementation. Its primary goal is to surface disagreements and risks early, when they are cheapest to resolve. Think of it as a forcing function that makes engineers articulate their thinking clearly.
Most design docs include sections such as: Overview, Background/Context, Goals and Non-Goals, Proposed Design, Alternatives Considered, and Open Questions. The Goals and Non-Goals section is especially valuable because it explicitly defines the boundaries of the solution. Alternatives Considered shows that the author has done due diligence and explains why the chosen approach is preferred. Not every doc needs every section — scope should match the complexity of the change.
An engineer drafts the document early in a project, ideally before writing any significant code, then shares it with teammates and stakeholders for review. Reviewers leave comments, raise concerns, and propose alternatives, which the author addresses through revisions. Once there is rough consensus, implementation begins with the doc as a reference. The doc often continues to be updated as the design evolves during development.
Writing forces clarity — an idea that seems solid in your head often reveals gaps when written down for others to critique. Design docs create a durable record of why a decision was made, which is invaluable for onboarding new teammates or revisiting a system months later. They also distribute ownership: when a team reviews a doc, everyone understands the system rather than just the original author. This reduces bus-factor risk and improves code review quality.
A common mistake is writing the doc too late — after the implementation is already done — turning it into documentation theater rather than a genuine design exercise. Keep docs concise; a 2-4 page doc that is actually read beats a 20-page tome that nobody finishes. Explicitly listing Non-Goals prevents scope creep and misaligned expectations. Finally, store design docs in a searchable, version-controlled location (like a wiki or a docs/ folder in the repo) so they remain discoverable long after the project ships.
© RM Full Stack & AI Engineer · All guides · Roadmaps · Open the app