Technical writers are often judged on the quality of the finished documentation. It is what customers, support teams, auditors, and internal users see.
However, a lot of documentation problems begin much earlier.
They begin when the writer is handed a Jira ticket or a pull request, a wiki page or a Word document, and they are expected to turn that into clear user-facing content.
Sometimes that source material is good quality. More often than not, it is incomplete. It’s missing information, such as the user’s goal and the workflow. They might be given information on a feature, but not information on who would use it, and why it’s important to the users.
Despite all that, the technical writing team will invariably get the job done. But they have to spend a large amount of time finding the missing information.
The problem is often upstream of writing
As we mentioned in How much time can technical writing teams really save with AI?, documentation work depends on people in other departments.
If SMEs do not give the technical writing team access to source information, test systems and release decisions, they and any AI system have little to work with. An AI system can derive clues from code, tickets or screenshots, but clues are not the same as clear source material.
It’s also true towards the end of a technical writing project: getting draft content reviewed for accuracy and completeness.
The consequence of these issues is that technical authors can miss the opportunity to become faster and more efficient.
For technical publications teams, the bigger efficiency gains are often upstream: finding, checking, and improving the source information before the writer starts authoring.
This matters because technical documentation is full of decisions that need source material:
- Who is this feature for?
- What problem does it solve?
- What has changed in the user’s workflow?
- What permissions are needed?
- What happens to existing customers?
- Are there exceptions, limits, or unsupported cases?
- Which existing topics, screenshots, procedures, and release notes are affected?
If those answers are missing, the writer has to ask.
Then wait.
Then interpret the answer.
Then check whether it conflicts with a ticket, a test, a product requirement, or the behaviour in the product.
It is easy to underestimate how much time this takes up, because it is hidden inside Slack or Teams messages, review comments, and “quick” clarification calls.
Brain dumps are not briefing packs
Development teams are usually trying to be helpful when they provide source material. The problem is that their source material is often shaped around their work, not the technical writer’s work.
A technical writer needs a different kind of handover. They need some sort of briefing pack that brings together:
- What the feature is
- Why it exists
- Who it is for
- The main workflow
- The constraints
- The open questions
- Links back to the evidence
Retrieval first, generation second
One of the proof-of-concept ideas we have been working on starts from a simple principle: retrieval first, generation second.
Instead of asking an AI tool to “write the documentation for Feature X”, the system starts with a known item, such as an Azure DevOps ticket. It then gathers evidence from related sources.
For example, a seed ticket might link to:
- A parent Epic
- Child stories
- Acceptance criteria
- Comments
- A pull request
- Commits
- An internal wiki page
- Test cases
- Release notes
The system follows explicit links first. It can also search for closely related material where links are missing, but with limits. The aim is to build a controlled evidence trail, rather than let the AI wander around the organisation looking for anything that sounds similar.
That evidence trail can reveal information no single person wrote down in a single place. For example:
- The Epic might explain the business reason
- A child story might describe part of the workflow
- A pull request might mention a new permission
- A test might reveal an exception
After the evidence has been collected, checked, and ranked, the system then produces a briefing pack for the writer.
This is closer to having a research assistant that finds the source material, points to where it came from, and says where the evidence is weak. In part, it’s working around the bottleneck to retrieve the information at source. Ideally, developers should be involved in providing the content, but this isn’t always possible.
Checking readiness before handover
Another proof of concept is a documentation readiness check.
The idea is to define what source information should be available before work is handed to the writing team. Not every feature needs the same evidence, so the standard has to distinguish between information that is always required and information that depends on the change type.
An AI-assisted readiness check can assess the available source material against those categories. It can then produce a status such as green, amber, or red, with the reasons visible.
It gives the developers an understanding of why the documentation is incomplete.
It also creates data for managers. If the same teams repeatedly hand over work with missing permissions or unclear user goals, the problem becomes visible. It can be improved as a process, not treated as individual friction between writers and developers.
Governance without the drama
This is where governance matters.
Governance does not have to mean a committee, a long form, or a workflow that everyone learns to avoid. In this context, governance means agreeing what evidence is needed before a feature is ready for documentation, where that evidence should come from, and who is responsible for closing the gaps.
Without that agreement, every handover becomes a negotiation. The result is inconsistent handover quality.
A documentation readiness standard, a definition of done, can make the expectation visible. It can also give product and engineering teams a clearer target.
Asking only what is still unknown
The third proof of concept is an adaptive documentation interview agent.
A fixed questionnaire can help, and so can a pass/fail criterion, but it can also annoy people. Developers and product owners do not want to answer questions that are already answered in the ticket, the pull request, or the product requirements document. They don’t want their work to be halted because the definition of done (provide the necessary information) hasn’t been met.
An adaptive interview works differently. It first checks the evidence already gathered. It looks at what has been answered, what is still unknown, and where sources conflict. Then it asks one useful question at a time.
If permissions are unclear, it asks about permissions. If the user goal is already well evidenced, it does not ask for it again. If the respondent says, “I don’t know”, the system records that honestly rather than inventing an answer.
This can be a better fit for documentation work because missing information is rarely uniform. The aim is to reduce clarification loops, rather than create a new admin burden.
The carrot, the stick, and the grit in the process
Getting developers to provide better source information is rarely solved by goodwill alone.
The carrot is obvious enough. Better handover means fewer interruptions later, fewer review comments, less rework, and documentation that is more likely to explain the feature accurately.
The stick is also available. A team can say work is not ready for documentation until the required information is present. It can add documentation readiness to release governance. It can make missing source information visible in a dashboard.
If the process is awkward, developers will work around it. Even a sensible process starts to look unreasonable when it adds grit to a busy release cycle.
That might mean meeting developers where they already work: Jira, GitHub, or Teams. In other words, building it into the development workflow.
It might mean pre-filling what can be found from existing source material, so the developers or product managers only need to be asked the missing questions.
The system should adapt to the type of change; otherwise the standard becomes noise. For example, a small UI change does not need the same handover as a new workflow.
Good governance sets the expectation. Good tooling makes the right behaviour easier than the workaround.
Where AI helps, and where it should not be trusted
AI is useful here because it can read across multiple sources, map evidence to required fields, identify gaps, suggest questions, and produce a structured briefing pack.
It should not be treated as the authority on product behaviour, but it can say, “The pull request mentions a new permission, but the acceptance criteria do not.”
It should not quietly decide how the product works when the evidence is absent.
Good documentation depends on source quality. AI can make poor source quality more visible.
What this changes for technical writing teams
For technical writers, this kind of workflow changes the point at which they add value.
They still write. They still structure information. They still decide what the user needs to know, what can be left out, and how to explain the task clearly.
However, they spend less time acting as detectives after the handover has already failed.
This is a better use of a technical writer’s time.
It also gives the writing team a stronger position in the product process. They do not have to receive whatever source material appears at the end. They can define what “ready for documentation” means, measure it, and help other teams improve the quality of handover without turning developers into unwilling documentation administrators.
Final thoughts
The problem is that technical writers often have to write from incomplete, scattered, and inconsistent source information.
AI can help most when it is used to retrieve evidence, check readiness, and ask better questions before authoring begins.
The human part of the problem still matters. Developers need a low-friction way to provide the information only they know. Technical writers need enough governance to protect quality without making every handover feel like a dispute.
It is a chance to move the conversation upstream, where many documentation problems actually start.
Note: We used AI to create the proof-of-concept apps, and ChatGPT to generate the images in this post. We also used Claude to proofread the draft.
Leave a Reply