Manage AI-driven docs contributions

Thu, 25 Jun 2026 21:59:53 +0000

AI tools make it easier than ever to generate content. With that ease, nearly anyone can become a contributor to the documentation. When people are using AI tools to create documentation, how do you maintain the quality, consistency, and accuracy of the content?

Fabrizio Ferri Benedetti proposes defining an AI policy for your documentation, with key recommendations to outline principles for using AI for documentation, define the tasks that need a human in the loop, request disclosure of AI tool use to create a feedback loop to learn from, and combine human review with deterministic tools.

That’s great advice, but I want to go beyond implementing a policy for AI usage. If you’re frustrated that people are producing low quality content that doesn’t meet your expectations or what you want to publish on the documentation site, make it easier on everyone by encoding your expectations in processes, documentation, and tooling.

Collaborate with contributors

People writing AI-generated content to send to customers (instead of the official product documentation) are not the enemy. Those of us writing official technical documentation have the same goal as folks writing unofficial content — to help customers (and prospective customers) use our product to get their tasks done.

How we help the user might look a little different, depending on our expertise, skill sets, and customer exposure. If you work with folks that are using AI to write unofficial product content or to contribute to the documentation site, get excited — someone cared enough about the customer to make content for them!

Channel the enthusiasm of potential contributors by starting a conversation. Be curious! Discover more about the content being created by your non-docs colleagues:

Why did they create this content? What was the motivation? What customer problem was it solving? Who is it for?
Do they know about existing documentation pages about similar topics, if they exist? If so, can they elaborate on what isn’t quite right about those pages, or the gap that the new content is filling?

Treat it like a user research exercise — what is your documentation not doing that this person wanted to fix by creating something else? Depending on what you learn, you can point them in the right next direction — another official content pipeline, a restructured documentation contribution, or a stamp of approval for their unofficial content!

The direction you point them depends on your content strategy…

Define a content strategy

Not everything is official product documentation!

People contribute content that they wrote because it was useful to them, or solved a particular customer’s problem, and they think it should be in the documentation. Sometimes people use AI to generate and create documentation-like artifacts, functioning as unofficial product documentation, without trying to contribute to the documentation directly. Sometimes people don’t know what’s already in the documentation — they didn’t check — they just had an idea and thought it would be a good thing to add!

Official product documentation is a contract with the customer about the supportable product functionality — here is what the product is, and how it works — but it doesn’t have to stop there. Product documentation can include best practices, recommendations, and conceptual overviews that teach people how the product works so that they can be more successful.

However, the content on a documentation site needs to be maintained, and some types of content lend themselves better to content types that can be published once and left to drift, rather than continually updated and maintained documentation.

To identify what content belongs where, define the content strategy. Sit down with your colleagues, or yourself, and answer the following questions:

What belongs on the documentation site?
What belongs on the company blog?
What belongs in internal sales enablement decks?
What belongs on the customer community forum?

Answering these questions, and doing additional work to define a content strategy, helps identify the right home for different types of content. With a content strategy, you can define a coherent voice and purpose for each content site and identify where different types of content belong.

If you have a defined content strategy, you have a clear direction to point potential documentation contributors if they, for example, want to publish marketing-style content about product functionality that isn’t fully implemented yet in the product (a blog post, for example).

A content strategy also helps you redirect technically correct content that otherwise doesn’t fit the function, architecture, or strategy of the documentation site, without having to offer a hard “no” to potential collaborators:

This deep dive into product architecture is a great idea for a blog post!

This decision tree for recommending different license models would make a great deck for training account executives!

This complex workaround for missing product functionality would be a perfect fit for a post on the community forum — it’s a niche use case, but super useful for the customers that need it.

To have conversations with potential contributors about your content strategy, you need to know where your contributors are, and they need to know how to find you.

Write contributing guidelines

If you produce an open source project with public documentation, you might already have documented contributing guidelines in a CONTRIBUTING.md file. If you work in a docs-as-code environment, you might have opened your repository internally to product managers, engineers, and support representatives to open pull requests to contribute. If you don’t work in either of those environments, you might have never thought about defining contributing guidelines for your content management system.

With the increasing use of AI assistants and tools in the workplace, it’s more common (and easier than ever before) for people outside the documentation team to contribute to documentation, no matter how you maintain and publish your content. If you don’t yet have contributing guidelines, it’s time to write some.

Start by documenting the expectations you have about types of content you want people to contribute to your documentation:

Fix typos and errors
Add a section to an existing topic, like a troubleshooting guide
Write a new user onboarding checklist
Provide real-world use cases and syntax examples

Outline these options that you might be willing to accept as direct content contributions, and also identify what is out of scope for contributions — rearchitecting the content, rewriting multiple topics — and offering alternatives or requesting that they contact the documentation team first.

Set up a triage process

Good contributions start with a conversation. You can’t have those conversations if people don’t know how to contact you and if you don’t make yourself available. The contributing guidelines help people know how to reach you. If you set up a triage process, you can have a plan to reactively and proactively interact with potential documentation contributors.

A triage process involves the following:

One or more ways to contact the team, such as with an email alias, a dedicated Slack channel, feedback on individual documentation topics, GitHub issues, a ticket creation form, and more.
A designated rotation of writers responsible for reviewing and responding to the incoming contacts.
A service-level agreement on the team of how often to review and respond to various types of requests.
Guidelines for what the expected output of the review and response process is.

I’ve had the most success in circumstances where one person is responsible for triage on a weekly basis. Having one designated person helps reduce context switching for the rest of the team, ensures responsiveness, and standardizes expectations that other teams might have for working with your team. Depending on the size of your team and the volume of contact input, you can experiment with other options.

Document style guidance

To ensure high-quality content contributions, you must document what “high quality” looks like for your documentation. You might have a fully detailed style guide, you might have chosen an industry-standard one to use and one page of documented product-specific style guidelines, or you might only have a list of low-level guidance that was documented on an as-needed basis:

How to handle a single item list
Whether to use sentence case for headings
The different meanings of may, might, and can
The ambiguity of once

A more detailed style guide likely cover guidance like how to refer to the user interface, how to structure links to other content, and task step formats.

However, if you are using a style guide developed exclusively for yourself or a small team of technical writers, you might forget to include technical writing best practices like:

Orient the user before giving an instruction.
Write user-centric headings to focus on the user task instead of the product feature.
Avoid future tense and the subjunctive mood to ensure clarity and precision of language.
Use plain language and avoid idioms and technical jargon.
Avoid terms like “easily” or “quickly” that make value judgments about a process.

You might also forget to document (the horror) standard practices on your team:

File name conventions for pages and images
Heading conventions for different doc types

Often, you might neglect to write these things down until you hire a junior writer that needs more guidance, or until your team grows large enough to where you can’t peer review each other’s work, or an editing team exists and can dedicate effort toward a style guide.

In the era of AI-generated documentation contributions, it’s essential to codify standard conventions, technical writing best practices, and nitpicky style guidelines in a style guide to increase the likelihood of higher quality contributions upfront, which can make reviewing and giving feedback on those contributions easier and quicker as well.

Add tooling to enforce style and best practices

Documenting style guidance is step one — enforcing it is step two! Make it easy on your contributors and yourself (and your teammates) by combining deterministic tools, like scripts and rules-based checks, with probabilistic tooling, like AI-driven audits and skills, that might be more comfortable for new contributors to interact with.

Some deterministic tooling that I recommend setting up in your documentation:

Vale to assess the style compliance of content, checking for errors like duplicate words, missing alt text for images, and warning for use of passive voice and future tense.
A tool like Doc Detective to assess the accuracy of your content.
An automatic link checker to ensure that links included in the content are valid. Many content management systems provide a link checker, but you can adapt a package like Lychee to run automatically.

If you are not in a docs-as-code environment, you can run some of these tools locally when you draft your content, explore similar functionality in your content management system (and request that your CMS add it), or lean more heavily on the probabilistic tooling options.

If you are getting AI-generated documentation, meet your contributors where they are. Consider providing the following resources to use with AI assistants to improve the quality of contributions:

Create a skill file to use for reviewing documentation, assessing important characteristics that are difficult to assess with a deterministic rule, like use of plain language, qualitative phrasing, overuse of feature names, and other style standards.
If using docs-as-code, a repo-specific agents.md file to provide instructions to an AI agent about content structure, semantics, and syntax expectations, including high-level style guidelines about header structure and task formatting.
Make your documentation available for semantic search by AI tools, using an MCP server or a service like Kapa, Inkeep, Fin, or Decagon, to help reduce the likelihood of duplicate or inaccurate content contributions.

If you find yourself consistently providing the same, repetitive review feedback, it’s a sign that you need to expand your style guide.

To improve accuracy of contributed content, explore a tool like Doc Sentinel AI, Promptless, or AI tools with the capacity to explore the product code base and answer questions about it.

The more tooling that you have in place to enable higher-quality contributions, the easier it can be to address a high volume of AI-generated unofficial product content.

AI-driven contributions don’t have to be sloppy

Don’t be exhausted by an inevitable future as a desperate defender of the documentation site from the incursion of AI slop. I’ve provided a comprehensive list of options, but remember: something is better than nothing, and all process is iterative.

Avoid sloppy documentation contributions with a combination of process, internal documentation, and effective tooling.

contributing guidelines on This is important