Scaling Documentation Infrastructure as Your Engineering Team Grows
On a Wednesday afternoon, support asks a reasonable question: what changed in the permissions flow that customers started using this morning?
One engineer points to a pull request. A product manager finds a Jira ticket with a different description. Somebody else pastes a Slack thread from two weeks ago. The help-center page still describes the previous behavior, which is technically impressive in the way a smoke alarm is technically a feature.
That is the point where scaling documentation infrastructure stops meaning “write more docs.” The practical answer is to make documentation a managed output of the engineering workflow. At roughly 15 engineers, teams need shared conventions and a merge-time record of user-facing changes. Somewhere between 30 and 50 contributors, they need automated collection of the evidence already created in pull requests, commits, issues, and releases, with a small human layer to validate and publish it.
The informal model worked because context was cheap. Once it is scattered across several teams and release cadences, the work changes. Documentation becomes the system that lets the organization answer, reliably and quickly, what changed, why it changed, who owns it, and what a customer needs to do next.
A scalable documentation system captures change evidence while it is fresh, turns it into audience-specific drafts, and routes those drafts to the people who can verify them.
The System That Worked At Ten People Has Already Retired
A five-person team can absorb an enormous amount of ambiguity. Everyone was probably in the meeting, reviewed the pull request, or at least knows who to ask. A few Markdown files, a Notion space, and a senior engineer with suspiciously good recall can carry more weight than they should.
The system looks lightweight. It is also drawing against a small shared pool of memory.
At fifteen people, that pool breaks into pieces. New hires begin learning the product through interruptions. One team’s release procedure lives in a repository, another team’s in a wiki, and the clearest explanation of an edge case is buried in a Slack thread that nobody planned to preserve. Across 79 agile practitioners from eight teams, more than half considered documentation important or very important while reporting too little of it in their projects.
That gap gets worse when the organization begins shipping several streams of work at once. The person who knows how a billing change affects an API consumer may be three teams away from the person announcing the release.
At 30 to 50 contributors, the operational question is no longer whether anyone cares about documentation. Most people do. The hard part is that no one person sees enough of the delivery system to reconstruct the release without going on a small archaeological expedition.
A 63-study mapping of documentation in continuous software development identifies a familiar cluster of causes: informal material becomes hard to understand, documentation drifts out of sync with the software, and teams focus on the short term. Its recommendation is revealing. Use development artifacts as a documentation source, then retrieve and transform them into useful documentation.
That is a much better description of the job than “tell engineers to write more.”
The cost arrives in small invoices. A support ticket takes longer because the answer exists somewhere but cannot be trusted. A senior engineer spends twenty minutes explaining a system to a new hire, then does it again next week. A pull request waits because the release note owner is trying to reverse-engineer what changed. A customer learns about an incompatible API change after their integration fails.
Trying to turn those into one universal dollar figure would produce tidy arithmetic and bad management. A productivity framework that spans satisfaction, performance, activity, communication and collaboration, and efficiency and flow also includes documentation and expertise discoverability, onboarding, handoffs, and wait time among useful signals.
Use that idea to measure the local cost instead. Track repeat support questions that link to stale or missing material, median time to get an accurate release note approved, the number of documentation-related PR blockers, onboarding time to a first independent change, and the share of releases with a customer-facing summary. The point is not to score writers or engineers. It is to find the friction that your organization is currently paying for in interruptions and delayed work.
A simple monthly estimate helps make that discussion concrete:
The estimate will be imperfect. It will still be more useful than treating the problem as an aesthetic preference for better prose.
Each Headcount Threshold Changes The Job
The first threshold asks for conventions. The next asks for a system. Past 30 people, that system needs to produce a useful first draft before a human begins writing from scratch.
From five to fifteen engineers, put the signal where the work happens. Add a required “user-facing changes” field to every pull request. Ask for the behavior change, affected audience, migration or configuration action, and whether a release-note entry is needed. A blank answer is acceptable only when the author explicitly says why the change has no external effect.
That field does two things. It makes the author decide whether the change matters outside the diff, and it leaves a structured clue for everyone downstream.
Keep the release-note taxonomy small. “Added,” “Changed,” “Fixed,” and “Deprecated” will outperform a twelve-category museum of product language. The goal is a consistent record, not a classification contest.
Require documentation work at merge time when the change meets the threshold. This can mean a doc update, an explicit exemption, or a generated draft awaiting review. What matters is that the decision travels with the code while the context is fresh.
Scalable release systems give teams self-service tools, enforce agreed policies through the normal workflow, and automatically archive a report of the changes in each release. Documentation benefits from the same architecture.
From fifteen to thirty engineers, move ownership from named heroes to teams. Every documentation surface needs a responsible team: API reference, developer onboarding, product help, release notes, or operational runbooks. That owner is accountable for the system and quality bar, not for typing every word.
This distinction matters. Individual ownership creates a vacation risk. Team ownership creates an operating responsibility that can survive turnover and distribution.
A practical ownership map usually has three layers. The engineering team supplies accurate change metadata in the pull request. The documentation owner for that domain reviews or approves material in their surface. A release or product-operations owner manages the publishing standard across domains.
Use repository-level review routing wherever possible. GitHub can automatically request review from the relevant owner when a pull request changes a matching path, and protected branches can require that review before merge. The workflow should route attention to the right people rather than depending on someone remembering a spreadsheet.
One qualification: route review to a team, not to the most competent individual you know. That person already has enough invisible work.
From thirty to fifty engineers, start treating documentation as a delivery artifact. The delivery system already knows a great deal about a shipped change: the linked issue, commit history, pull-request description, code paths, labels, test results, feature-flag status, and release version. A mature documentation flow captures that evidence automatically, generates a draft appropriate to the destination, and sends it through a review step.
The output need not be a single document. A customer-facing release note, an API reference update, a migration guide, a support brief, and an internal runbook have different audiences and standards. They can share the same source evidence while retaining separate templates and owners.
A release can combine code, binaries, documentation, and release notes and be created from a CI/CD job. That is exactly the right mental model for this stage: the release record is part of producing software, rather than a separate errand scheduled after the fact.
A pull-request template can stay short:
The template is not the infrastructure. It is the handle that lets the infrastructure pick the change up.
Let The Workflow Do The Collecting
The usual response to documentation drift is to hire a technical writer. That can be a smart move, especially when a product needs better information design, an API needs a coherent narrative, or a regulated customer base needs a rigorous publication process.
A writer cannot attend eight standups, inspect every pull request, resolve every ambiguity, and create every changelog entry on a team of fifty engineers. The information simply reaches them too late and from too many directions.
The operating models look different once that constraint is made explicit.
The third model scales because it changes what humans spend their time on. The system gathers and structures evidence. A writer, product-operations manager, or senior engineer decides whether the explanation is accurate, useful for the intended audience, and consistent with the product’s vocabulary.
That is a much higher-leverage job than manually finding each change.
Automation also changes the speed-versus-quality trade-off that teams often treat as permanent. Workflow-connected automation gives speed and consistency because it begins from the delivery artifacts. Human validation adds context, catches an important exception, and keeps the overall structure coherent. Those are complementary jobs.
A useful review queue should show the source links behind every draft, the destination, the release version, the accountable team, and a status such as “needs product context” or “ready to publish.” If an editor has to re-open four tools to verify a claim, the system has only moved the scavenger hunt into a nicer interface.
AI belongs here precisely because it is designed into the workflow. The system connects it to the approved pull request, code, tests, tickets, labels, and release version that define a change. It can then synthesize a customer-facing release note, draft an API description, or flag likely documentation drift with the relevant evidence attached.
That is intentional architecture. Guided generation applies destination-specific templates to the delivery artifacts engineers already review, so a release note, API update, or support brief begins with the operating context that makes it useful. Human review adds product judgment and meaningful nuance, while recurring edits improve the next draft.
A blank prompt still has a place for exploration. Production documentation needs a source trail, editorial standards, and a review route built into the system from the start.
A lean technical writing team still has plenty to do. It owns content standards and templates, improves the information architecture, identifies recurring gaps, trains teams to provide better metadata, and reviews the documentation that carries higher customer or compliance risk. It also feeds recurring review edits back into the system, so the next draft starts closer to the organization’s actual standard.
The four failure modes tend to recur.
Adding headcount without fixing information flow. A writer who receives late, unstructured, incomplete updates will produce late, incomplete documentation with better punctuation. The collection mechanism needs attention first.
Treating documentation as optional at the release boundary. If the release can happen before anyone records the customer impact, the record will eventually fall behind. One sprint of drift becomes two. Soon, the team is “catching up” on material that no longer has an obvious owner.
Optimizing for internal explanation while external communication decays. Internal architecture notes are valuable. Customers and support teams still need clear release notes, current help content, and reliable API references. Track both surfaces separately.
Automating without enough structure. Workflow-embedded AI performs best when the source metadata is specific, the destination is explicit, the accountable owner can review the result, and examples establish the quality bar. Those inputs are part of the product design, not cleanup work after generation.
At fifty engineers, good documentation operations feel almost boring. A merged change with user impact creates a draft through the release pipeline. The relevant team can review it in context. One designated owner validates the release notes before publication. API and help material update through reviewable pull requests. New hires can find the current explanation without learning the organization’s social topology first.
The critical question is whether the team can reconstruct what shipped without launching an investigation.
Doc Holiday is built for that job: it reads the engineering workflow already producing commits, pull requests, and tickets; it generates documentation and release-note updates on merges and releases; and it delivers those updates as reviewable pull requests. The people closest to the product still set the standard. They simply no longer need to collect every scrap of evidence by hand.
