Where Should You Keep Your Design Docs?

Ask any engineering team, “Where do you store your design docs?” and you’ll get a dozen different answers, a few strong opinions, and at least one rant about a tool that “almost worked.” If you’re reading this, you’ve probably wrestled with the same question and maybe even switched tools more times than you care to admit.

Let’s break down why there’s no one-size-fits-all, the real pros and cons of the popular approaches, and what to actually optimize for as your team grows.

Why Do We Care So Much About Design Docs, Anyway?

First, a quick reality check:

Design docs aren’t just for process points or CYA. They’re where ideas are hammered out, risks are surfaced, tradeoffs are weighed, and the why behind the code is documented. Months later, when someone wonders, “What were we thinking?” that doc is the answer key.

But how do you keep them accessible, useful, and actually read (not just written)? That’s where things get spicy.

The Contenders: Where Teams Actually Keep Their Design Docs

1. Collaborative Docs (Google Docs, Coda, Notion, etc.)

These tools are the crowd favourite for a reason:

Pros:

• Real-time editing and comments make it easy for multiple engineers to hash out ideas together.

• Linking, formatting, and embedding diagrams or pseudo-code is simple.

• Everyone in the org can access and comment, not just engineers.

• “Single source of truth” folder structures (when you’re disciplined).

Cons:

• Lacks tight integration with the codebase.

• Docs can get lost in a sea of folders if not organized well.

• Referencing code snippets works, but doesn’t feel “part of the repo.”

• Not great for referencing in code reviews or tracking along with code changes.

2. Markdown (in the Codebase, with Mermaid/Diagrams)

A classic for “living next to the code”:

Pros:

• Easy to keep docs up to date as code evolves.

• Clear version history and tight coupling to pull requests or features.

• Markdown is lightweight, and Mermaid diagrams add visual context.

• AI agents and search tools can easily index them.

Cons:

• Collaboration is…painful. Real-time editing? Forget it.

• Docs “pollute” the repo and sometimes the IDE search.

• Not friendly to non-engineers (or, let’s be honest, many engineers) who hate writing prose in Markdown.

• If your team owns multiple services, duplicating patterns can be a pain.

3. Wiki Platforms (Confluence, Notion Wiki, GitHub/GitLab Wiki, etc.)

Enterprises and startups both go here:

Pros:

• Discoverable by the whole org (if permissions are handled well).

• Can be linked from tickets, PRs, or directly referenced in code comments.

• Stronger structure, cross-linking, and sometimes richer diagram support.

Cons:

• Slow to update if you want “living” docs—collaboration isn’t always seamless.

• It can become a graveyard of out-of-date docs if nobody’s tending the garden.

• Commenting is often a second-class experience.

• It may not integrate well with your code or repo activity.

4. Diagram-First Tools (Miro, Excalidraw, Whiteboards, etc.)

For teams who think visually:

Pros:

• Fast brainstorming, free-form thinking.

• Easy to share and embed visuals in other docs.

Cons:

• Not searchable or discoverable unless embedded elsewhere.

• No “why” or “decision” context unless paired with prose.

• Not tied to codebase changes or version history.

The Real Tradeoffs (And Why You Can’t Have It All)

Every tool is a bundle of tradeoffs.

• Easy collaboration vs. proximity to code

• Discoverability vs. signal-to-noise

• Support for rich visuals vs. searchability and versioning

• Cross-functional participation vs. engineering-centric workflows

Teams that put everything in docs platforms love the collaboration, but groan about tracking alongside code. Teams that keep everything in Markdown love the discipline, but hate that nobody outside the codebase will ever read them or that commenting and iterative brainstorming are just awkward.

And then there’s the universal fear: design doc bloat. If you include every bit of low-level detail, pseudo-code, and diagram in your design documents, will your repository become a swamp? Will your documentation grow so large that your IDE groans every time you search for a method name? Or will your docs become a forgotten time capsule, only cracked open when something breaks?

What Actually Matters (The “North Star” for Design Docs)

After all the tool debates, the advice from teams is surprisingly clear:

• Collaboration beats everything. The easier it is to comment, edit, and iterate together, the better your docs (and your decisions) will be.

• Optimize for the “why,” not just the “what.” Document the reasoning, not just the chosen approach; future you will thank you.

• Link liberally. Wherever the docs live, link them from tickets, PRs, and code comments. Make them discoverable at the moment they’re needed.

• Shared ownership matters. Keep docs in team spaces, not personal drives. Use clear naming and folder structures so docs don’t get lost.

• Adapt to the team’s workflow. Visual teams may thrive with diagram-first docs; engineering-heavy teams may prefer everything in markdown. There’s no “best,” just “best fit.”

  
  

And finally: Don’t let perfect be the enemy of done.

It’s better to have “pretty good” docs in a tool everyone uses than perfect docs in a place nobody checks.

Still arguing about docs in your team chat? You’re not alone. Every team fights this battle, and there are no silver bullets, just tradeoffs that (hopefully) match your team’s style. Good luck, and may your design docs never become ancient runes only decipherable by their original authors.