Ask any engineer where the documentation is and you get the same shrug. There is a wiki. Nobody trusts it. The onboarding guide was written by someone who left eighteen months ago, the runbook stops at step four, and the API reference describes two parameters that were renamed last quarter.

This is not a tooling problem. Teams have had wikis, doc generators and templates for twenty years. It is an incentive problem. Writing documentation is work that lands on whoever cares most, pays off for someone else, and never shows up in a sprint review. So it gets deferred, and the deferral compounds until the docs are worse than nothing, because now people read them and act on stale instructions.

What has changed in the last two years is that the expensive part of the job got cheap. Producing a competent first draft used to take an afternoon of focused writing. It now takes a few minutes, which changes the calculation on every document a team has been avoiding.

The material is already there

The reason Artificial intelligence works better on internal docs than on marketing copy is that the source material exists and it is specific.

A merged pull request contains the change, the reasoning in the description, and the objections in the review comments. A design doc contains the decision and the alternatives that lost. An incident channel contains the actual sequence of what broke and what fixed it, written by people under pressure, which is usually the most honest account you will ever get. A ticket contains the requirement in the words of the person who wanted it.

Feed that in and you get a draft that is grounded in your system rather than in generic advice about your system. That distinction matters more than model choice. A model working from your ADRs and your incident timeline writes something a new hire can follow. The same model working from a one line prompt writes an article about the importance of documentation, which nobody needs.

What teams are actually producing

Three kinds of document come up again and again when you ask around.

Onboarding handbooks are the most common starting point, because the pain is measurable. Somebody new joins, spends a week finding out which of the four staging environments is the real one, and asks the same eleven questions the last hire asked. Teams are now generating a first version of that handbook from their repository structure, their README files and the questions already sitting in the new hire channel, then having two engineers correct it. The output is not brilliant writing. It is accurate enough to stop the eleven questions, which is the entire point.

Runbooks are the second. After an incident, the retrospective already exists as a channel full of messages and a timeline. Turning that into a numbered procedure while it is fresh is exactly the task that gets skipped when everyone is tired and the fire is out. Doing it the same day, from the channel history, means the runbook exists at all.

Reference documentation is the third and the most careful. Generating prose descriptions from type definitions and function signatures works well. Generating behaviour claims does not, because the model will confidently describe what a sensible function would do rather than what yours does. Teams that get value here keep the generated layer strictly descriptive and write the behavioural notes by hand.

Structure before prose

The pattern that separates teams who get something usable from teams who get a pile of plausible text is the order of operations.

The instinct is to ask for the document. What works better is to agree the shape first, then fill it. Decide the sections, decide what each section has to answer, decide who the reader is and what they already know. Only then generate. A handbook drafted section by section against an agreed outline stays consistent, because each part is written against the same plan rather than against whatever the model happened to say two paragraphs earlier.

This is the same lesson people learn writing anything long. Tools built for book length work, like an AI book writer, put the outline first and generate each chapter against it for exactly this reason, which is why chapter nine still agrees with chapter two. A fifty page internal handbook has the same failure mode as a novel. Drift.

The practical version for a team is dull and effective. Write the table of contents yourself. Ten minutes. Hand the model one section at a time with the relevant source material attached. Review each section before moving on.

Where it goes wrong

The failure modes are consistent enough to list.

Documentation with no source of truth behind it is the biggest one. If the model is generating from nothing but a prompt, you are producing confident fiction and putting it somewhere people will trust it. Every generated document needs a named input, and if you cannot name the input, the answer is not to generate it.

Flags, defaults and version numbers are where hallucination concentrates. These are the details a model will fill in with the most common value it has seen elsewhere, and they are also the details someone will copy into production. Check every one.

Staleness does not go away. Cheap generation makes it worse in one specific way, because now there is more documentation to go stale. The teams handling this well tie regeneration to the change that caused it. The pull request that renames the parameter also updates the doc, in the same review, or the doc is wrong by the end of the week.

And review effort is real. If the generated draft is 80 percent right, the remaining 20 percent is scattered through the text and has to be found. That is faster than writing from scratch, and it is not free. A team that treats generated docs as finished is shipping a worse wiki than the one they had.

What this changes about the job

Speed is the least interesting part of this. What changes is which half of the job matters.

Knowing what a document has to contain, who reads it, what they will get wrong without it, and which claims are dangerous if they are wrong. That is judgement and it sits with the people who understand the system. Turning that judgement into paragraphs always felt like the work, and it was never where the value was.

For most teams the honest summary is that AI removed the excuse. The handbook that has been on the backlog for two years is now an afternoon of work rather than a week, and the reason it still is not written is no longer capacity.

Starting this week

Pick the document that costs you the most in repeated questions. It is usually onboarding.

Write the section headings by hand. Gather what you already have: the README files, the design docs, the questions people have already asked in the channel. Generate one section, correct it, then do the next. Have someone who was not involved read the result and try to follow it, and fix whatever they get stuck on.

Then decide who owns keeping it current, and tie that to a real trigger rather than a good intention. That last step is the one that decides whether any of this survives past the first month.