voice typing design docs rfcs: A Practical Guide to Voice Typing for Design Docs and RFCs

Voice typing design docs RFCs before the design is settled is the fastest way to find the holes in your own argument. Most design documents fail in the writing, not in the design: the author spends an evening formatting sections and two sentences on the actual reasoning. Flip the order. Open a blank document, start recording your thinking out loud, and produce the argument before you produce the outline. The argument is what gets reviewed; the format is what gets skimmed. Speaking the argument forces you to state it in one coherent pass. The outline follows the argument, never the other way round.

The reason voice helps here is the gap between thinking and typing. You can defend a design in conversation long before you can commit it to prose, because conversation lets you follow the objection as it arrives. Dictation keeps that conversation and turns it into text you can edit, so the transcript becomes the first draft. You do not start from a blank page; you start from the version of the design you already said out loud. For engineers, this is the difference between a document that exists and a document that ships. The first draft is the conversation, and the conversation is the more honest of the two.

Set the honesty bar before you speak. An argument-first doc has to survive a hostile reader, so invite the objections while you narrate: say what a reviewer would hate, what the obvious alternative gets right, and where the proposal is weakest. Naming the weakness in the doc is cheaper than defending it in a review. Write the skeleton after the argument, not before, so the sections serve the reasoning instead of the other way around. If you cannot say it, you do not know it yet. A weakness named in the document is a weakness that cannot ambush you in review. State it plainly.

A problem statement that fits in one breath is a problem statement that fits in a review. Say it out loud: the current system does X, and it breaks when Y, and that costs the team Z per week. If you need two breaths, the problem is still two problems, and the doc should say so. Dictate the statement while the pain is fresh, then check it against the evidence: the dashboard, the incident, the pager history. Statements that cannot be tied to evidence are opinions, and opinions do not survive review. One breath is the standard, and the standard is what keeps the scope honest.

The one-breath rule also sets the scope of the document. Once the problem is stated in a single sentence, everything the doc contains must support it: the background supports it, the options answer it, the plan fixes it. Sections that do not serve the problem statement either belong in a different document or belong in the introduction as context. Speaking the problem first makes the scope obvious, and scope is where design docs normally die. A clear problem statement is the cheapest way to kill scope creep early. Scope creep enters through the sections that do not defend the problem statement. Cut them early.

Write the problem statement with the numbers you can defend. Say the request volume, the latency, the paging rate, or the failure count, and cite where the number came from: the metric dashboard, the error log, the ticket queue. If the number is a guess, say it is a guess and say what measurement would confirm it. Reviewers trust a document that knows the difference. Dictated problem statements tend to be better here because you say the number you actually remember rather than the one that looks clean. A stated guess with a measurement plan is a fact with a due date. That is enough to review.

Commitment is the expensive part of a design, so do it after the walkthrough: say the design into the document as a proposal, then defend it against the alternatives before you write the implementation plan. Walk the flow aloud from start to finish, in the order a user or a request would experience it, and mark every point where the design forces a choice. Those marked points are the sections a reviewer actually reads. Speaking the flow also catches the steps you would have skipped in writing, because your mouth refuses to gloss over a hole that the page would hide. The flow is the design, and the design is the flow.

Say the design the way you would explain it at the whiteboard: this is the shape, this is why it is a pipeline and not a queue, this is what it does on the first request and on the tenth. Then translate the spoken explanation into the document's core section, keeping the causal order. Design docs that read like conversations are easier to review than docs that read like specifications, because the reasoning is visible. A reviewer can argue with a narrative; she can only annotate a spec. Dictate the reasoning before you translate it into formalism. Narratives invite argument; specifications invite annotation, and argument is the point.

Then make the commitment explicit. After the walkthrough, dictate one paragraph that states the decision and the conditions: we will adopt this design unless X or Y shows up in the pilot. Put that paragraph in a visible box, because decisions with escape conditions are easier to approve than decisions with none. Note the date of the decision and who owns it. Design reviews are arguments about trade-offs, and the argument is better live. The document is the artifact; the decision is the event. Escape conditions are the honesty of a decision, and honesty is what the review tests. Write the date next to the decision.

The section that separates a good RFC from a form is the alternatives section, and it is the easiest to dictate because you have already considered them all in conversation. List three alternatives and give each one the fair version of its argument, not the straw version. Say what each one wins on and what it loses, then say why the winner wins. A doc that argues honestly with its alternatives gets approved faster than a doc that pretends there was one option. Reviewers do not veto a choice; they veto a hidden one. The fair version is the version your opponent would write.

Dictate the trade-offs as actual trade-offs, not as a balance sheet. Say: the in-memory cache is faster to build but loses to the database on restarts; the database version costs a migration but survives deploys. State the operational cost in concrete terms: paging, maintenance, the person who has to own it. Then state the non-negotiable requirement that decided the issue. Speaking the cost plain is the same instinct as telling a colleague the real price. Documents save the most time when they save the argument from repeating. Saying the operational cost plain is what makes the trade-off real rather than rhetorical. Give the number.

Keep a placeholder for the decision that is not yours to make. Say what the committee or the owner must rule on, and what information would help them rule. Dictate the open questions as questions: does the platform team accept the new dependency, is the migration window agreed, who funds the pilot. A design doc that names its open questions honestly is easier to act on than one that hides them under a risk section. The open questions are the agenda of the review meeting. The open questions are the agenda, and the agenda is the part of the meeting that moves. Bring them ready.

The transcript is not the document. Convert it in one pass: speak the whole argument, then edit for structure, cutting the restarts, the hedging, and the second attempts. Keep the conversational phrasing in the sections that carry reasoning, because it reads better than boilerplate; formalize only the parts that will be quoted or implemented. Then fill the sections in the order the readers follow: problem, context, options, decision, plan, verification. A dictated draft shortens the writing from a weekend to one session. One session beats a weekend because the transcript carries the reasoning in the order you made it. Edit by section, not by sentence.

Send the draft for review with the argument first. Put the decision and its reasoning in the top section and the mechanics after, so a reviewer can evaluate the choice without reading the implementation. Ask for specific review passes: one for the problem statement, one for the alternatives, one for the plan. Dictate the review response rather than typing it, and fold every accepted change into the document the same day. The document that gets reviewed in passes gets better than the one that gets reviewed once. Review passes are cheaper than a single comprehensive pass, because each pass has a job.

Close the loop with a short verification section. Say how the design will be tested once built: the metric that proves the problem is solved, the rollout window, the rollback trigger. Then confirm that the doc matches the delivered system after implementation and dictate the corrections when they diverge. A design doc that stays current is the reason the next RFC gets written faster. The review is a cost, but the document is an asset, and assets pay for themselves. The verification section is where the document earns the next one. And the divergence list is where the document stays honest. Check it at the postmortem too.