Goals and non-goals: the section a reviewer approves first

The win for today: the goals section of the DocuDex doc rewritten so a reviewer can agree with every goal and still argue with the design — plus an open-questions list at the end. About thirty minutes; the material is your own doc from lesson 1.

1. Why the goals section is reviewed first (4 min)

Sourcegraph's RFC process, as captured in their handbook, moves a doc through explicit labels. Under "Reviewing problem", the RFC "has a firm problem statement, and reviews should focus on confirming that the problem definition is correct". Only once "the problem is well understood" does it move to "Reviewing solution". The same handbook wants the problem statement to say "why this problem is worth solving now", and the background to be "indisputable facts, not opinion" — the context-section rule from lesson 1, stated by the reference employer. HashiCorp goes further and splits the two into separate documents, a PRD for the problem and an RFC for the solution (writing practices and culture). Either way, the goals section is the contract the design is judged against.

That is why a design choice disguised as a goal is a problem and not a nitpick. If "ship as a CLI" is a goal, then agreeing with the goals means agreeing with the CLI, and nobody ever gets to ask whether a CLI was the right call. You have smuggled the solution past the problem review. It also weakens the alternatives section later: you cannot honestly consider alternatives to something you have already declared mandatory.

Ubl's Design Docs at Google gives the flip side for non-goals: they are goals you could reasonably have had and are explicitly rejecting — his example is a storage system listing "ACID compliance" as a non-goal. A good non-goal makes a reader think "oh, I'd assumed that was in".

2. Sort your own bullets (6 min)

These are the bullets from your DocuDex doc, plus two lifted out of the prose. Sort each one. No looking back at the doc.

3. Rewrite a design choice as the goal underneath (5 min)

The move is always the same: ask "what would be true for the user if this worked?", write that, and push the means down into the design section where it can be argued with.

Two more things a goal should carry. It should be testable — "few necessary commands" is a feeling, "init, add and serve without reading a manual" is a test someone can run. And where a goal is not obvious, one clause of why: "docs pinned to the dependency version, because stale docs are worse than no docs for an agent".

4. Do it (15 min)

Open the DocuDex doc and rewrite the goals and non-goals section.

1. For each bullet, run the test: could a different design satisfy it? If not, move the bullet to the design section and write the outcome that was underneath it as the goal.
2. Add the missing goal about versioned docs.
3. Make each goal testable. If you cannot say how you would check it, it is either a design choice or a wish. Also add one line to the context section on why now — Sourcegraph's "worth solving now" — since agents reading docs offline is the timing argument and the doc never quite says so.
4. Non-goals: keep the four you have. For each, add a short clause on why, so a reader does not assume you forgot ("no TUI for the MVP — the web app gives search and navigation for less work; a TUI can come once the storage format is stable").
5. Add a final section, Open questions, and move the four questions that are currently inside paragraphs there: the agent interface, how to fetch docs beyond Go, user-defined sources, and the business model. Give each a line on what would resolve it. Lesson 3 comes back to the first one.

5. Retrieval (2 min)

One of these is from lesson 1. No looking back.

Read next

Ryan Singer's Write the pitch from Shape Up — ten minutes. Its "no-gos" section is non-goals under another name, and its "appetite" is a constraint most design docs forget to state: how much time this is worth. Add an appetite line to the DocuDex doc if it changes anything.