cassiobotaro

Design docs, part 5: tools, references, and a demo

Mon, 29 Jun 2026 00:00:00 +0000

We’ve reached the last part of the series. We’ve already looked at what a design doc is, how to fill in each section, and how it lives over time. What’s left is the most practical part, the one that shows what to write with, where to dig deeper, and how an AI agent can hand you a first draft.

Tools for writing Link to heading

Confluence. Atlassian’s corporate wiki for creating documents with team collaboration. It integrates with Jira and Bitbucket.
Google Docs. Online and free, with real-time collaborative editing and easy sharing.
GitHub. It hosts code and also Markdown documents, with collaborative editing through Pull Requests.

Tools for diagrams Link to heading

Mermaid. Diagrams as text: sequence, use cases, C4, and more.
Sequence Diagram. Dedicated to sequence diagrams, textual and quick.
Structurizr. Diagrams as code: several C4 architecture diagrams from a single model.

The C4 and sequence diagrams that show up in part 2 were made with tools like these.

Design docs, part 4: lifecycle, when not to write one, and other documents

Mon, 22 Jun 2026 00:00:00 +0000

In the previous parts we filled the document out from top to bottom. Now the focus shifts: how a design doc lives over time, when not to write one, and which other documents travel alongside it.

The lifecycle Link to heading

A design doc is living documentation. It isn’t born complete, and it doesn’t die once the code ships. The typical path looks like this:

Design docs, part 3: alternatives, cross-cutting concerns, and more

Mon, 15 Jun 2026 00:00:00 +0000

In part 2 we described and justified the design of the solution. But a good document also shows the paths you didn’t take and what your solution affects beyond your own team.

⚠️ A quick reminder: the sections that follow are examples and recommendations, not a mandatory template.

Alternatives considered Link to heading

Here you list the alternative systems or solutions you evaluated, explaining the trade-offs and the reasoning behind the final choice.

Design docs, part 2: the design

Mon, 08 Jun 2026 00:00:00 +0000

In part 1 we put together the beginning of the design doc for our fictional case, the Inventory Replenishment Recommender: headers, overview, scope and context, goals, and non-goals. Now we get to the heart of the document.

⚠️ As always, the sections here are examples and recommendations, not a mandatory template.

The design Link to heading

A quick clarification: the “design” isn’t a single section, it’s a set of them. Depending on the project, it unfolds into several parts, each with its own heading:

Design docs, part 1: what they are and how to start the document

Mon, 01 Jun 2026 00:00:00 +0000

A design doc is a relatively informal document that the main author (or authors) of a software system writes before diving into the coding project. It captures the high-level implementation strategy and the key design decisions, with an emphasis on the trade-offs weighed along the way. In other words, it’s where we record the rationale behind the chosen solution, the alternatives, the goals, and the architecture, in a clear and shareable way, before spending time writing code.