Why nobody reads your design doc, and what gets one read

A design doc gets read when it asks named people for a specific decision by a specific date, fits in one sitting, and says what silence means. Most unread docs fail the first test: they describe a system and ask for nothing, so nobody knows they are the one who has to answer.

We call that the reader's contract, and this guide is how to write one into a doc. It is about getting a design doc read and decided, not about what sections a design doc needs; for the anatomy, Michael Lynch's guide to writing an effective design document and Malte Ubl's Design docs at Google are the two to read. The contract is the same for a technical spec or a PRD: a product requirements document that names the decision it needs from engineering gets read for the same reason.

The five steps

1. Put the ask on page one. State the decision you need, who makes it, the date you need it by, and what silence means, before any context.
2. Cut it to one sitting. A reader should finish in about twenty minutes. Everything else goes in an appendix.
3. Get one reader before the crowd. A single trusted reviewer reads first and fixes the obvious, so the wide review starts from a doc worth reading.
4. Decide what silence means, and write it down. Silence is consent after a window, or silence blocks the work. Either is fine. Undefined is not.
5. Ask for "yes" or "not yet", then close it. Never "any comments?". Record the decision and mark the doc as decided.

If you have a doc open, jump to Step 1. The next section is why these five.

What people argue about when "nobody reads it" comes up

"Nobody reads them" is the oldest complaint about specs. Joel Spolsky wrote in 2000 that it is the biggest complaint from teams that write them: the spec goes on a shelf and the product gets built "without any regard to what the spec said, because nobody read the spec, because it was so dang mind-numbing" (Painless Functional Specifications, part 4).

Twenty-six years later we wanted to know what people say when the subject comes up now. On 14 September 2026, Lynch's guide to design docs became the top Hacker News thread on the subject so far this month, with 348 points and 141 comments from 92 people. Livemark read every comment and coded each one by its main point on 17 September 2026. The numbers below are counts of comments on that one public thread, coded by one person; the method and its limits are at the end of this page.

Four things in that thread decide how you should write your next doc.

The unread complaint is real and small. Six of 141 comments on the top Hacker News design-doc thread of September 2026 so far said the problem is getting anyone to read the doc; a second pass with a keyword search for reading and skimming found seven. Add "too long" and "AI-generated slop" and reader-side friction is 16 comments, roughly one in nine. Among the 31 comments that opened a conversation rather than replying to one, two were about reading.

The fight is whether the doc is worth writing at all. Forty-five of the 141 comments on that thread, nearly a third, argued whether design docs are worth writing at all, and the defenders outnumbered the "just build it" side 32 to 13. One skeptical top-level comment, to the effect that a design doc had never improved a process and the team should build the thing instead, collected 73 replies: that one argument is 74 of the 141 comments, from 53 people. Of the 32 defenders, seven say the point is that writing forces the author to think the problem through, six that it is how several teams or vendors come to agree, and two that a five-page design is easier to review than the design hidden in ten thousand lines of finished code.

A quarter of the thread was about AI, almost all of it in one argument. Thirty-one of the 141 comments argued over whether cheap AI-written code changes the need for a doc: try three real implementations instead of three proposals, against the doc being the only human-authored text an agent can check its work against. Five more said the design docs now crossing their desk are generated. Only two of the 31 opening comments raised AI; the rest is replies.

Nobody proposed naming who answers, or by when. The symptom was on the table three times. One top-level comment was the plain ask, that the writer's current problem is getting people to read their design docs, and its three replies offered AI as the disruptor, a low signal-to-noise ratio, and one invested reviewer first. Another described a process where everyone was invited to sign off and, as far as the writer could tell, one person did. A third said badly written docs end with a call to explain the whole idea. None of the replies said: name the deciders, set the date, say what silence means. A keyword check agrees, for what a missing word is worth: across all 141 comments, none uses "deadline" or "silence", three mention signing off, two say "approval" or "approvers", and four say "reviewer". The review process got 15 comments in total, most of them about getting a team to write docs at all and who is blamed when the code diverges. On the top Hacker News design-doc thread of September 2026, the reader's contract was not on the table.

That gap sits under all three fights. One defender put the bridge in a sentence: when you need buy-in from people outside your team, you probably need a design doc. A doc that asks for nothing is not worth writing, gets skimmed, and is exactly what an agent will generate thirty pages of. A doc that asks named people for a decision by a date is worth writing because the decision is the product, and it gets read because someone knows they owe an answer.

Step 1: put the ask on page one

Lynch's page-one rule is that some readers "will see the doc before hearing any explanation from you". Most guides read that as "put the context first". Put the ask first, then the context. Call it the TL;DR if your template has one; it carries four lines:

• Decision needed: the one question this doc exists to settle, as a question. "Do we move session storage to Redis before the multi-region launch?" For a PRD: "Do we ship usage-based pricing before the self-serve launch, or after?" Not "Session storage design" or "Pricing requirements".
• Deciders: the two or three people whose "yes" is required. Names, not a team alias. For a design doc that is usually the engineers who own the neighboring systems; for a PRD, the engineering lead and the designer.
• Needed by: a date. Rina Artstain's version of the rule is blunt: "If you leave things open-ended and depend on people's good will, they may not get around to reviewing your document" (How to write an effective design document, 2022).
• If you say nothing: what happens on the date without an answer. Step 4 covers the choice.

A reader who only sees the first screen now knows whether they are a decider, what they are deciding, and when. Everyone else knows they are being informed rather than asked, and can skim without guilt.

If you cannot write the decision line, you have found out something about the doc. Ubl's account of design docs at Google (2020) says to skip the doc when the solution is unambiguous or the doc would be an implementation manual with no trade-offs in it. A doc with no decision in it is that manual. Write the one-paragraph note that says what you are going to do instead.

Step 2: cut it to one sitting

Web reading studies are about web pages, not specs, but they are the closest thing to a reading measurement we have. In Jakob Nielsen's 1997 study, 79 percent of test users scanned any new page they met and 16 percent read word for word (How users read on the web). His 2008 calculation from instrumented browsing, 25 users and 45,237 page views, put the ceiling at 28 percent of the words on a page, with 20 percent more likely (How little do users read?). Your reviewers are those people, on a busy Tuesday, with your doc as the ninth tab.

Amazon's answer was to fix the reading time and let the length follow. Jeff Bezos's 2017 shareholder letter describes the six-pager, a narrative memo read silently "at the beginning of each meeting in a kind of 'study hall'" (2017 letter to shareholders). Colin Bryar and Bill Carr's Working Backwards (2021) gives the arithmetic: about three minutes a page, twenty minutes of the hour, which is what makes it six pages. Ubl's account of Google's guidance runs longer, "around 10-20ish pages" for a large project with one-to-three-page mini docs for incremental work.

Pick the Amazon budget unless you are certain your readers will book their own time: the decision and its reasoning in what a person reads in twenty minutes, about six pages, everything else in an appendix. Done looks like this: a decider who starts at the top reaches the recommendation, the rejected alternatives and the open questions inside twenty minutes, and everything past that point is in an appendix. A doc that needs an hour is one that gets scheduled for "later".

Two mistakes hide inside "keep it short". The first is cutting the alternatives, which are the part a reviewer needs to judge the recommendation; for a PRD the alternatives are the scopes you are not shipping. The second is a revision that grows: Roman Kashitsyn's guide notes that "making engineers re-read new revisions of a document is nearly impossible" (Effective design docs, 2024). When you revise, add a "what changed since the last version" block at the top so a second read costs two minutes, not twenty.

If you generate the draft

In the 2025 Stack Overflow developer survey, 30.8 percent of respondents said they now document code mostly with AI and 30.3 percent partially (Stack Overflow Developer Survey 2025). Roland Huß's line about the cost is the one to remember: "the person who generates 30 pages saved an hour, but the 10 people who have to read it lost a day each" (AI wrote it. Nobody read it., 2026). A generated draft is a fine starting point. The AI argument on that thread ends where this guide does: a model can write the context, the alternatives and thirty pages of design. It cannot name the deciders, choose the date, or decide what silence means, because those are commitments rather than text. One defender on the thread made the same point from the other side: let a teammate go straight from idea to implementation with an agent and the agent may pick a library that is disallowed for some customers or an API the company is moving off, so the trade-offs have to be discussed with the humans who know the system. If a generated doc has no four lines on page one, it will be read the way it was written: by a model, for someone who did not.

Step 3: get one reader before the crowd

The guides agree on the first reader, and it is the step people skip because it feels slow. Send the draft to one trusted reviewer first. Kashitsyn's warning is that if you ask for feedback too early, "your colleagues will point out the most obvious flaws and probably never give your document another chance". Lynch names what goes wrong without a first reader: many simultaneous reviewers "might all assume they can give it a quick skim because somebody else will review it carefully" (Useful feedback on design docs, 2025). Lynch is describing the bystander effect: by his reasoning, a design doc sent to twelve people at once gets fewer real reads than one sent to two.

Pick someone who is not a decider, so they read to help rather than to judge. Ask them for two things only: state the decision line back to me, and tell me where you stopped reading. Give them a day. Fix what they found in the doc, not in a reply thread. The wide review then starts from a version that survives a skim. If your first reader cannot state the decision line back to you, page one is not done yet.

Step 4: decide what silence means, and write it down

Apache, Rust and Squarespace each have a rule for silence. The how-to guides mostly leave it implicit, and nobody on that thread mentioned it: it is a choice the author makes, on page one, before the doc goes out. On the date, some deciders will not have answered. What happens?

There are two answers, and both are in use.

Silence is consent. The Apache Software Foundation calls it lazy consensus: state your intent publicly, wait "usually 72 hours", and "Silence indicates consent" (Lazy consensus). Objections must come with a reason. This is fast and it respects reader attention, because a reader who agrees does not have to do anything. It suits changes that are reversible and teams that trust each other. The IETF's older cousin is rough consensus, which RFC 7282 defines as reached "when all issues are addressed, but not necessarily accommodated" (RFC 7282, 2014): every objection gets an answer, not every objector gets their way.

Silence blocks. Squarespace's rule after they rebuilt their RFC process: "If the approvers don't say yes, we won't start implementing" (The power of "Yes, if", 2019). Rust's RFCs sit in the middle: a final comment period "lasts ten calendar days, so that it is open for at least 5 business days", and "Before actually entering FCP, all members of the subteam must sign off" (Rust RFC process). Explicit sign-off suits changes that are expensive to reverse and decisions that cross team boundaries.

The mistake is leaving it undefined, which produces silent approval. Tanya Reilly's account of Squarespace's old process describes it: "If a reviewer had no objections to make, they didn't call out that the design was good; they usually said nothing at all." The author could not tell approval from absence.

Whichever you choose, the review window matters as much as the rule. Apache's 72 hours and Rust's ten days bracket the range; Lynch gives reviewers "a minimum of two working days" for a first read. Artur Pan, writing for an RFC tooling vendor in 2026, puts the rule of thumb as anything shorter than three days creating a race where senior engineers "approve by default because they haven't had time to read", and anything longer than fourteen killing momentum (RFC process for engineering teams); one vendor's opinion, but it matches what the named processes converge on.

Async review or a meeting

One commenter on that thread described the failure the choice is about: badly written docs end with getting the author on a call to explain the whole idea, which is the async model collapsing into a meeting without the meeting's one advantage. Amazon's study hall guarantees the read: twenty minutes, in the room, before anyone speaks. Sending the doc to a team list, the lightweight end of the range Ubl describes at Google, guarantees nothing, which is why it needs Artstain's date and a rule for silence. Squarespace's Architecture Review guarantees a decision: fifty minutes of discussion and ten for the answer. Lynch puts the meeting last, after two working days of reading alone, and only for the contentious items. If your team will not hold the reading time in a room, you are running the async model, and the async model only works with a date and a silence rule on page one.

Done looks like this: the four lines on page one now include "If you say nothing by the 24th, we proceed" or "We do not start until all three of you have answered", and everyone on the doc can see which it is.

Step 5: ask for "yes" or "not yet", then close it

"Any comments?" invites the review that goes wrong: typos, naming, a paragraph on a tangent, and no answer to the decision. Squarespace replaced it with a question every approver has to answer: yes, or not yet, and what would have to change for it to be yes. Their design review gives each major RFC an hour, and "the final 10 minutes of the meeting are for making the decision", with each person saying whether they are comfortable or what would change their mind. The framing is in the title of Reilly's post, "The power of 'Yes, if'".

The same shape works asynchronously. Ask each decider for one of two answers by the date: yes, or not yet, because X, where X is a change you can make. A dependency outside the doc is a not-yet too; name it. Anything else is a comment, welcome but not an answer. Long threads on one point move out of the doc: Lynch parks threads beyond two or three exchanges in an open-issues appendix and holds one focused meeting at the end for the contentious items only; Angela Zhang's older rule of thumb is that any thread past five comments should move to a live conversation (How to write a good software design document, 2018).

A yes is a commitment to the decision as written, and the thread had the rule for what happens when the decision moves. Lynch's own reply on the thread, for requirements that change during implementation: ask whether the reviewers would have withheld their sign-off had the change been in the doc they reviewed, and if so, send it out again and say why. Another pair of commenters argued over reviewers who lack the knowledge to critique a design, and the retort stands: if they do not have it before the code is written, they will not have it at code review either. A change that would have changed the answer reopens the doc.

Then close it. A decided doc that still reads like a proposal will be re-litigated by the next person who finds it. Phil Calçado's RFC process (2018) carries explicit document states, Draft, Feedback Requested, Active, Abandoned, Retired, and a rule that "Authors must address all comments written by the deadline" (A structured RFC process). Oxide's RFDs move from prediscussion through discussion to published, committed or abandoned (RFD 1). Kubernetes enhancement proposals move from provisional to implementable only when the named approvers say so (KEP process). If your tool has no states, write the decision and the date at the top of the doc and stop editing it. For the durable record, that is what an architecture decision record is for. An RFC explores a decision; an ADR records one. Every decider's answer is then visible on the doc, its state says decided, and the date is where the next reader sees it first.

The contract in practice

At the process level, the clearest before-and-after anyone has published is Squarespace's, because the same team ran both. Before: an Infrastructure Council met every two weeks and got through three RFCs an hour; authors presented and felt like they were "running a gauntlet"; reviewers with no objection said nothing, so approval and absence looked the same. After: approvers are named in the RFC header; the answer is "yes" or "not yet", never "no"; Architecture Review meets twice a week, about ten people, one RFC per hour, fifty minutes of discussion and ten for the decision; and nothing starts until the approvers say yes. Same company. What changed was the contract: who answers, what an answer is, and what happens without one.

At the doc level, here is the smallest real one we have, the decision that produced this page. Livemark keeps a queue of the questions only a person can answer, and every row has the shape of page one: the question, what is blocked until it is answered, the lettered options with a recommendation, the answer, and the date it closed. The row for the guides read, in full: the site has no content surface, and every piece of writing is blocked until it has one; (a) build it, one route and Markdown in the repository; (b) not yet, keep the site to the homepage; (c) content lives elsewhere. Recommendation: (b), because nothing could be measured yet. Decider: me, one name. The silence rule is the queue's own: an open row is restated in every report until it is answered, so nothing gets written in the meantime. The answer was (a), on 16 September, in three words, and the row was stamped closed the same day. Step 3 was skipped, and honestly: with one decider and a four-line note there was nobody to send it to first. The whole thing is shorter than this paragraph, and it was read because it asked.

Livemark's review flow is this contract with the states filled in. Setting a document to Open is the ask, and only an Open document can be given reviewers, by name; any member of the team can name them. A reviewer answers Ready or Not yet; the status carries no reason, so the reason goes where it can be replied to, in a comment thread. Whoever can edit the document can ask again, which resets every reviewer to pending. When the last reviewer says Ready the document is Approved; a reviewer changing their answer sends it back to Open. The decision line, the date and what silence means are still yours to write on page one.

Common mistakes

• Asking a team instead of people. "Infra team, please review" is a request nobody owns. Two names, or three, and their answers on the doc.
• A deadline with no consequence. A date that passes with no rule for silence is a suggestion. Step 4.
• Wide review before a first reader. The obvious flaws get found in public and the doc never gets a second chance.
• Answering "any comments?" with fixes to the prose. Reviewers do what they are asked. Ask for a decision.
• The revision that grows. Each round adds a section and nobody re-reads. Cut, and put "what changed" at the top.
• Sending the generated draft. Thirty pages a model wrote and you did not read. See "If you generate the draft" above.
• Treating a moved requirement as an edit. If it would have changed a reviewer's answer, it goes back to review.

The case against all of this

The strongest argument against this guide is that the doc is the wrong artifact, not the wrong contract. Lucas F. Costa puts it directly: "The doc's job was never to guide the implementation. Its job was to get sign-off", and "Two weeks of coding would have told you more about your system than two weeks of writing about it" (Design docs, 2026). Doug Turnbull's version is that "a prototype can be worth 1000 design docs" (Throwaway PRs, not design docs, 2024). Jos Visser argues that "if a design review is an approvals process, it is almost by definition a train wreck", because reviewer capacity becomes the bottleneck (Never approve design docs). Jacob Kaplan-Moss's case against RFCs is that they reward the people who can write to exhaustion (Against RFCs, 2023).

Three of those points are right. A decision that a two-day spike can settle should be settled by the spike; Costa concedes cross-team coordination as the case where the doc still wins, Turnbull concedes that and long-horizon work, and those are the docs this guide is about. Named approval does concentrate load, which is why Step 4 offers silence-is-consent as a legitimate choice for reversible decisions and why the window is short. And Kaplan-Moss's own concession is the point of this guide: RFC processes work "only if there's a well-designed decision-making process: document, discuss, and then decide". The unread design doc is usually the one that stopped at discuss. The one measurement pointing the other way is DORA's 2021 report, which found about 25 percent of respondents had good-quality internal documentation and that those teams were 2.4 times more likely to have better delivery performance (Accelerate State of DevOps 2021); that is documentation in general, and it says nothing about cause.

Start here

Open the doc you are waiting on someone to read. Write the four lines at the top: the decision as a question, the names, the date, and what silence means. Send it to your first reader.

Frequently asked questions

How long should a design doc be?

Long enough to read in one sitting. Amazon fixes the reading at about twenty minutes, roughly six pages at three minutes a page. Google's guidance is ten to twenty pages for a large project and one to three for a mini doc. Put the decision, the recommendation, the rejected alternatives and the open questions inside that budget.

Who should review a design doc, and who approves it?

One trusted reader first, then the two or three people whose "yes" is required, named on page one. Everyone else reads it for information. Uber's process had a few named approvers sign off before work started and then sent the doc to every engineer (Scaling engineering teams via writing things down, 2018).

How long should reviewers get?

Between Apache's 72 hours and Rust's ten calendar days, with Lynch's minimum of two working days for a first read. For contrast, Google's code-review guidance sets one business day as the maximum time to respond to a review request (Google engineering practices); a design doc needs longer because the question is bigger.

Should I write a design doc if nobody will read it?

Write the one-paragraph decision note instead, unless the decision crosses a team boundary or is expensive to reverse. If it does, the doc is worth writing, and the reason nobody reads it is that it does not yet ask anyone for anything. Put the four lines on page one and send it to one reader.

Does this apply to a PRD or a technical spec?

Yes. A PRD says what to build and why; a technical spec or design doc says how. Both go unread for the same reason, and both get read once page one names the decision and the deciders. A PRD's deciders are usually the engineering lead and the designer; a design doc's are the engineers who own the neighboring systems.

What is the difference between an RFC and an ADR?

An RFC explores a decision and asks for input; an ADR, an architecture decision record, records a decision already made, with the context and the alternatives considered. A design doc that has been decided should be summarized by an ADR, so the next reader finds the decision and not the argument.

Are design docs a waste of time?

In Livemark's coding of the top Hacker News design-doc thread of September 2026 so far, the people saying yes were outnumbered 32 to 13. Costa, the strongest written case against docs, concedes coordination across teams; Turnbull concedes that and work that reaches years ahead. For those decisions the doc is worth writing, and worth getting read.

Method and limits

The figures on this page come from one Hacker News thread, item 49696125, a discussion of Lynch's guide posted on 14 September 2026. Livemark fetched all 141 comments through the Hacker News Algolia API on 17 September 2026. At fetch it had 348 points, 31 top-level comments and 92 distinct commenters, and the article's author wrote 14 of the comments. One person read every comment and assigned it one main theme from a ten-theme codebook: docs are worth it; what AI changes; the review process and adoption; what belongs in a design doc versus a spec; not worth it, build instead; off-topic, 12 comments kept in the denominator; praise and structure tips; nobody reads them; too long; AI-generated slop. Fourteen of the 141 assignments were judgment calls, the largest group between "worth it" and "not worth it". The "nobody reads them" count was checked a second way with a keyword search, which found seven against the six coded. The 74-comment subtree and every denominator were recounted from a second fetch the same day. The 32 "worth it" comments were then read again for what each says the doc is for. The coding sheet and the script that produces every number above are public; the script fetches the thread itself.

This is one thread, about one article, over the three days after it was posted, among self-selected Hacker News readers who skew senior and opinionated. Percentages are over comments, not people, so a long argument between two people inflates its theme. Keyword counts are counts of comments containing a stem, and a missing word is weak evidence. Treat all of it as a reading of what engineers argue about, not a survey of what they do. We will not refresh the count; it is a dated snapshot. The process pages cited for Apache, Rust, Kubernetes, Oxide and Google's code review are living documents and were read on 17 September 2026.