The POC write-up: a question, some evidence, a recommendation

The win for today: a one-page POC write-up, recommendation first, on the riskiest assumption in your design doc — that docs derived from Go source cover what a real project's dependencies actually document. This is the longest lesson in the course: a two-hour time-boxed POC plus thirty minutes of writing. If two hours are not available this week, section 4 says how to do the writing half on a POC you have already run.

1. Where the shape comes from (5 min)

Nobody has published the canonical POC template, so the reference sheet is a synthesis and says so. The three sources it draws on:

Shape Up's Write the pitch gives you appetite — how much time this is worth, stated before you start, so "we ran out of time" is a finding rather than an excuse — and rabbit holes, the parts that would eat a real project if not decided now. A POC is the cheapest place to find rabbit holes.

Oxide's RFD 1 has a state machine that ends in committed or abandoned, and keeps abandoned documents published. A POC that ends in "don't build this" has succeeded; the write-up is how that success is not lost.

Ubl's Design Docs at Google notes that prototyping can be part of the design process. Your design doc already flagged the assumption ("this is an assumption so I've to test this"). The POC is the test; the write-up is what closes the open question.

The shape, then: recommendation (first line), question, appetite, what was built, what was found, rabbit holes and next. The full table with budgets is in the reference.

2. Question or wish? (5 min)

A POC question has to be able to come back "no". Sort these.

3. Recommendation first (4 min)

The same findings, written twice.

4. Do it (2 h + 30 min)

The POC (two hours, hard stop). Question: does go/doc over the module cache give usable reference docs for every dependency in a real go.mod? Pick a Go repo of yours with real dependencies — Ink or Bunko. Write the smallest Go program that:

1. reads go.mod, resolves each module path to its directory in the module cache (go list -m -json all gives you Dir),
2. runs go/doc (or shells out to go doc -all) over each package and writes the result to a Markdown file,
3. prints a table: module, version, packages found, packages with empty docs, bytes written, seconds taken.

Then pick five dependencies you know keep guides on a website and check by hand whether anything you would actually need is missing from the output. Do not build the CLI, the manifest or the SQLite index. Everything here is throwaway; say so in the write-up. When the two hours are up, stop, even if it is not finished — "did not finish X" is a finding.

The write-up (thirty minutes). One page, in the six-part shape. Recommendation on the first line. Numbers everywhere you are tempted to write an adjective. Name the packages that failed. Include the surprise — there is always one. End with the rabbit hole and the next step, and close the open question in the design doc by linking the write-up from it.

5. Retrieval (2 min)

One of these is from lesson 4.

Read next

Shape Up's Write the pitch if you skipped it after lesson 2 — the rabbit-holes section in particular. Then skim Oxide's RFD 1 for the state diagram; five minutes.