Trade-offs and alternatives: make the design section argue

The win for today: the three design paragraphs of the DocuDex doc — CLI, storage, serving — rewritten so each names what it cost, and an alternatives section that mirrors them: for every choice, the option it beat and why. About forty minutes. Start from the lesson 2 draft.

1. Why the cost is the part that matters (4 min)

Ubl's rule from Design Docs at Google is that the design section should focus on trade-offs rather than implementation detail — the doc exists to surface the decisions a senior engineer might make differently. A paragraph that only gives reasons reads as finished; there is nothing for a reviewer to push on except "I disagree", which is not useful to either of you. A paragraph that names its cost invites "is that cost acceptable?", which is a conversation with an answer.

The Rust RFC template makes this structural. It has a Drawbacks section whose whole prompt is "why should we not do this?", and a Rationale and alternatives section asking why this design is the best in the space of possible designs, what other designs were considered and why not, and what the impact of not doing it would be. Steal the drawbacks question: every design choice gets asked "why not?" before it is written down.

Ousterhout's A Philosophy of Software Design supplies the vocabulary for many of the costs you will name: complexity is anything that makes the system harder to understand or change, and it accumulates from dependencies and obscurity. "This choice adds a second storage format that has to be kept in sync" is a complexity cost, and it should be said in those words.

2. Which of your paragraphs argue? (5 min)

These are the design paragraphs from your draft, compressed. Sort them.

None of the five has a cost. That is not a criticism of the thinking — you know the costs, which is why you could sort them — it is the gap between knowing and writing.

3. The four-part paragraph (5 min)

Here is your CLI paragraph rewritten in the form. Same decision, same reasons.

Two things to notice. "Rather than a desktop app or editor extension" names the alternative inside the choice; that sentence is what the alternatives section will expand. And "I accept that because…" is the sentence that makes it a decision rather than a list of considerations.

4. Do it (25 min)

Rewrite the storage and serving paragraphs in the four-part form, and add a short one for the manifest. For each, before you write, answer the drawbacks question on paper: why should I not do this? If you cannot think of a reason, you have not found the alternative yet.

Prompts, so you do not have to invent the alternatives from nothing:

• Storage. SQLite plus Markdown, versus SQLite only (Markdown in a column, FTS5 over it — one file, one thing to back up, but agents can't cat it), versus Markdown only with an index built in-process at serve (no database dependency, but search quality and startup cost). Name the cgo question: mattn/go-sqlite3 needs a C toolchain and complicates cross-compiling a single binary; modernc.org/sqlite is pure Go and slower. Which, and why?
• Serving. A local HTTP server versus a static site written to disk and opened from a file URL versus, later, a TUI. What does a server buy that static files don't (search endpoint, live reload on sync)? What does it cost (a port, a process to leave running)?
• Manifest. A hand-maintained manifest versus deriving the doc set from go.mod on every sync. If go.mod is already the list of dependencies with versions, what does the manifest add — pinned extra sources? A lockfile of what was fetched? Say which, or say the manifest is not needed for the MVP.

Then rewrite Alternatives considered so it mirrors the design: one short entry per design choice, naming the option that lost and the trade-off that decided it. Your current entries (scraping, hosted, TypeScript) are about scope; keep them, but move them under the goals or non-goals they justify. Finally, take "via godoc" out of the goal it is still attached to and let it live here, as the choice it is.

5. Retrieval (2 min)

Two of these are from earlier lessons.

Read next

The Rust RFC template itself — five minutes. Read the section prompts as questions to ask of your own doc, not as headings to copy. Then, if you have twenty minutes more, chapter 2 of Ousterhout ("The nature of complexity") gives you the words for the costs you are about to write.