Documentation gets five kinds of review, from people who can skip it

A spec moves through statuses — draft, in review, approved — and each change of status implies that someone checked something. An interview study posted to arXiv on 26 August 2026 looks at a sibling artifact, software documentation, and asks how its quality is actually achieved. The answer is a series of reviews by different people, coordinated by a writer with no authority to make any of them happen.

The study

The paper is by Avinash Bhat and Jin L.C. Guo of McGill University, Ian Arawjo of Université de Montréal and Disha Shrivastava of Google DeepMind. It is to appear at GROUP '27, the ACM conference on supporting group work.

The team interviewed 31 experienced technical writers, recruited through the Write the Docs Slack (12) and LinkedIn (19). Participants came from startups, enterprises and open-source projects in fields including data platforms, security, hardware, military and aviation. Interviews lasted 45 to 70 minutes, and participants were encouraged to share their screens to show how they worked. The coding followed Kathy Charmaz's grounded-theory method.

The authors then sent a summary and the full draft to all 31 participants. Thirteen responded, and twelve confirmed that the analysis matched their experience.

Five stages, five kinds of reviewer

The writers described five review stages. The number beside each is how many participants mentioned it, which the authors stress is not a measure of how common or important the stage is.

• Self review (27). The writer runs the documented steps against the software, cross-checks Jira tickets and recorded meetings, and checks hard topics with subject-matter experts.
• Technical review (28). Usually the developers who built the feature, checking accuracy and completeness. These sessions also surface knowledge that never appeared in development tickets or feature specifications.
• Editorial review (28). Other writers check language, structure and readability. Product owners and managers sometimes join to make sure the wording neither overpromises nor creates legal exposure.
• Play testing (13). Someone who did not contribute, often from QA, follows the document end to end to catch what the writer assumed the reader already knew. Participants called it informal and opportunistic, and mostly reserved for tutorials.
• Post-publication feedback (18). Support tickets, site analytics, votes and comments. None of these was built to measure documentation quality, so each needs interpretation.

The stages can come in any order, repeat, and overlap. Regulated industries such as aviation and the military ran formal change requests and approval workflows. Teams that prioritised fast releases ran shorter processes, and writers who were the only writer on their team published with no editorial review at all.

One line from the technical-review section will be familiar to product managers, because it is about them:

If I'm lucky, the product manager will take a look, but usually they just say, 'Yeah, sure, fine, looks good.'

Where review breaks

The second half of the paper catalogues the challenges, and most of them are about people and timing, not writing.

Documentation starts too late (21 participants). It lags behind engineering sprints. One writer described getting a request when development was about 90% complete, with a week to write an 86-page integration guide. Another described subject-matter experts asking for a whole new section without the deadline moving.

Nobody is obliged to review (17). Reviewers put their own work first, and writers can only persuade them. Some reported being treated as the person creating extra work.

Review becomes a formality (19). When the author knows the product better than the reviewer, review turns into a rubber stamp. One participant said they read everything from junior writers and only check senior writers' work for typos. Others described reviewers approving without reading: opening the document, reading the title, the first line and the headings, then saying it looks good. Reviewers also tended to read long documents carefully at the start, then skim or stop before the later sections.

The tools were built for code (21). Product managers and other non-technical reviewers did not like reviewing in pull requests, so writers fell back on Google Docs or PDFs and then copied the changes back by hand.

LLM feedback was hard to trust (25). Writers had to split long documents to fit context windows, and could not paste in the internal context a review needs, from tools such as Confluence and Jira, for confidentiality reasons. Several also described the models as eager to please. One put the problem precisely: an LLM "doesn't know what to look for if something is missing."

What worked was mostly social. Writers opened pull requests early with specific questions for named reviewers, asked things only an engineer could answer, moved hard questions to calls, and when all else failed escalated to management or discussed reviews in public channels where silence was visible.

The caveats, from the paper itself

• One side of the story. Every claim about reviewers is the writers' account of reviewer behaviour. Writers may not know how developers, managers and other reviewers experience the same process, or what workarounds happen outside their view.
• A particular kind of writer. Participants were experienced writers at organisations that invest in dedicated writing roles and tend to have more systematic processes. The authors say the study may miss novice writers, developers, program managers, and organisations with informal review.
• Structure may be overstated. Looking for recurring stages may have played down informal practices that fall outside them.
• Counts are not prevalence. Stages identified later in the study were not asked about in earlier interviews.
• Qualitative coding without a reliability score. The first author ran every interview and led the analysis. The team used peer debriefing and reflexivity instead of an inter-rater statistic.
• A dissent in the validation round. One participant argued that quality rests mainly on the writer's own understanding of the software, with review as a check, not the source of quality. The authors say their findings support that for senior writers.

What it changes about a spec's lifecycle

A PRD is not user documentation, and nothing here was measured on specs. But the review problems the writers describe are not specific to documentation. They come from the same arrangement: one person accountable for a document, and several people who could improve it but have no reason to.

A status hides which review happened. "Approved" can mean an engineer walked the flows, or that someone read the headings and said it looked fine. If your spec has a lifecycle with named statuses, each move into "in review" or "approved" should say who reviewed which part. Product sign-off and engineering feasibility are different checks, the same way technical and editorial review are.

Ask questions, not for a review. The writers who got substantive feedback sent specific questions to the person who could answer them, early. That is the same pattern we saw in a study of stalled pull requests, where review most often ended because nobody knew whose move it was.

Expertise gaps produce rubber stamps. A senior PM's spec reviewed by someone with less context gets the typo pass. That is the review most worth giving a structure, so that reviewing someone else's PRD means reading past the first page.

Late review cannot verify. Documentation written at 90% done describes a build nobody can still change. A spec reviewed after the build has started has the same problem.

And the PM as reviewer is the uncomfortable part. In the quote above, the product manager is the one saying it looks good. When you review someone else's document, you are on the other side of exactly this problem.

FAQ

What was studied? How 31 experienced technical writers get documentation reviewed, through semi-structured interviews.

The five stages? Self review, technical review, editorial review, play testing, and post-publication feedback.

Why does it break? Late requests, reviewers with no obligation, rubber stamps, skimming, tools built for code, and LLM feedback writers could not trust.

The lesson for specs? Make each status change name who reviewed what, and ask reviewers specific questions.