Home »

Write the Docs Newsletter – June 2026

Salutations, documentarians. I’m writing to you from a trip up to Estonia, where the days are longer than I’ve experienced in a while. The way the light stretches on makes it seem possible to accomplish more in a single day. It brings a sense of optimism that maybe we can solve more problems, whether they are big, global ones or just finally fixing those outdated articles I’ve been meaning to get to. I hope you can manage to find time to fix some problems too.

The year will also stretch on for a while more, so we have three larger events coming up. First is Write the Docs Kenya on 8 August, then Write the Docs Berlin on 6–8 September, and then Write the Docs Melbourne on 3–4 December. I hope you can make it to at least one.

This month we have articles on dealing with people sharing unofficial docs, whether to flag content that had an assist from an LLM, some thoughts about whether docs can ever be too comprehensive, and some ideas on how AI search can be done well. Enjoy!

Dealing with shadow docs

A recent #ai channel discussion focussed on a growing problem of “shadow documentation”: where non-documentation teams – such as Support, Sales, or Customer Success – use AI tools to generate PDF files and guides for customers from official documentation. (This has been done in the past without AI involvement.) Participants agreed that the issue is becoming more common as AI tools make it easy to generate customized onboarding, deployment, or troubleshooting materials.

Documentarians are primarily concerned with the accuracy, version, supportability, and governance of these docs. AI-generated documents may become outdated quickly because of a lack of oversight and may contain invalid, hallucinated, or unsupported functionality based on the AI prompts used.

Shadow docs (whether AI-generated or not) often circulate without the documentation team’s knowledge. This can be a governance issue. Also, non-docs teams may create unofficial content when official documentation is incomplete, difficult to use, or insufficiently tailored to specific customer workflows. Some non-docs teams create unofficial docs because they face customer pressure and operational realities. But even with robust official documentation, if people receive shadow docs, they’re unknowingly using something that may be out of date instead of accessing the up-to-date official documentation.

The discussion suggested different strategies for handling the problem of shadow docs.

  • A governance-focused approach: Clarifies ownership and accountability for unofficial content. The documentation team should know about any shadow docs to vet them properly and make sure to redirect the shadow docs to the maintained content. Alternatively, encourage teams to share URLs to maintained content rather than distributing AI-generated docs.

  • A partnership model: Incorporates field-generated knowledge back into the official documentation set. AI-generated content can provide value when used internally for improving official documentation if the output is reviewed and validated. The documentation team may need to put into place procedures for making verified “rogue” content accessible to other teams.

  • Doc customization: Adds customized content into the official documentation – such as curated collections of official topics.

Shadow documentation can be an organizational challenge that requires balancing governance, usability, customer needs, and evolving AI-generated content.

See more Write the Docs resources about working across roles.

Flagging AI content in documentation

Should you flag AI-generated content in internal or external docs? It’s tempting to reach for a label, but is such a label actually useful? Members of the WTD community discussed the different angles in Slack this month.

AI has given every department the ability to generate many pages of content and drop them in the company intranet. Management of internal documentation often lands on the docs team, officially or not. Tools such as Confluence and SharePoint make labeling easy, so it’s tempting to identify AI-generated content to give a heads-up to the reader. The writer’s impulse is understandable: this content hasn’t been reviewed by a human yet, read with caution.

But an “AI-generated” label might not convey the meaning you intend. Technical readers may already expect AI authorship. And if management has encouraged AI use across the organization, they may read the label as a positive marker of adoption. To differentiate human-reviewed content from AI noise, it may be better to add a “needs review” label or, better still, tighten the publishing workflow itself to require sign-off before content goes live.

With user-facing documentation, the impulse to label human-reviewed AI content is about trust. Writers want to be transparent and disclosure feels like the honest thing to do. Here too, the label may be misinterpreted.

Many readers are skeptical of AI, so labelling human-reviewed AI content may undermine confidence rather than build it. For others, that same label might do the reverse – one contributor speculated that AI-generated code samples might actually inspire more trust than human-written ones. On the legal side, the question of whether we’re obliged to disclose was raised, though the general view was that human-written content can be just as wrong as AI-generated content. Ultimately, people come to your documentation to solve a problem. The main concern for users is not “How was this created?”, but “Is it useful?”.

This is a moment in time. The labeling question may look very different in a few years. If you do use labels, think carefully about what job you want them to do and how they will land with your audience and your organization. In both cases, a human in the loop remains a standard worth sticking to.

See more Write the Docs resources about AI and LLMs.

Can docs be too comprehensive?

A recent discussion about whether docs can ever be too comprehensive was sparked by feedback to a documentarian that a particular guide was too comprehensive for most users, since the full document was only necessary for a small percentage of use cases. The central question was how to address this – whether through a separate “light” version of the guide or some other approach.

Several structural solutions emerged as the most practical responses. One such solution was breaking content into smaller, meaningful chunks, including separate pages when practical. Others mentioned using progressive disclosure, where readers are shown the content in a simple version and enabled to drill into detail as needed. Separating content by user role or task (or persona) was also suggested, particularly for audiences with distinct needs, such as admins versus end users.

There was a brief debate about whether documentation can ever truly be “too comprehensive”. Some held that gaps are always worse than over-documentation and that the real problem lies in how the content is presented rather than how much there is. Others countered that overloading users prevents them from finding a clear path from where they are to where they want to be – if they see all the content and feel overwhelmed, they may never get the information they were seeking.

The core challenge may be delivering the right content to the right persona at the right time. This may mean creating a quick-start guide for most users while preserving the full details for those who need it. Think carefully about how to structure and filter your content to best match your audience’s needs.

See more Write the Docs resources about writing doc sets.

Doing AI search well

Many documentarians are in search of a proficient AI search function. Some have been tasked with incorporating this feature within product help menus or in lieu of a standard search option.

A recent Slack discussion sought out illustrations of how a chatbot-like search could enhance the user experience. When it cites page links as references, AI search may empower users to read and verify the information sources themselves. Someone suggested adding a chatbot to the side of a page as an alternative to replacing traditional search features altogether. Several companies are already implementing this side-by-side framework, serving up AI search as a supplemental conversation tool.

There are various patterns in use with search infrastructure. One company features separate lexical and AI searches that don’t communicate with each other, while another employs a window with lexical search results and generated suggested queries that the user selects to invoke AI search. Some documentarians were adamant that AI search should supplement, rather than replace, traditional search experiences. As an example combined offering, Cloudinary won the 2025 Dev Portal Award for best AI-powered developer portal.

Ultimately, documentarians might benefit from adding AI search to a doc set because it responds to natural language queries and returns a full response with context. Users can ask simple or complex questions and receive dynamic answers that reach beyond just a single page or section (such as including information from both user guides and an API reference). AI search may even facilitate open-ended questions that don’t relate to the pages at hand by pulling information from a different location. Users don’t have to rely as much on key word precision or technical jargon to achieve their desired results.

AI search is a potent tool that can at times respond better to user intent (rather than user action), enrich documentation as a knowledge base, and speed up the search process by bridging connections between topics and ideas.

See more Write the Docs resources about AI and LLMs.

From our sponsor

This month’s newsletter is sponsored by Document360.

Document360 logo

Most days, the writing isn’t the hard part. It’s everything around it like the outdated articles, the missing context from engineering, the same reader questions arriving in different shapes. The craft gets squeezed into the gaps.

Document360’s AI is built to fill those gaps. A writing agent that turns a prompt or a video into a structured draft. A search that knows what a reader actually means. A chatbot that handles repeated questions. A connection to the LLMs your team uses, so your docs are cited, not guessed at.

It’s an assistant. Not a replacement. The voice stays yours. Talk to our specialists.

Interested in sponsoring the newsletter? Take a look at our sponsorship prospectus.

Write the Docs resources

Write the Docs offers lots of valuable resources related to documentation. See all of the Write the Docs learning resources. To discuss any of these ideas or others related to documentation, join the conversation in the Write the Docs Slack community in one of the many channels.

Events coming up

Portland 2026 Recap - Talk Videos, Photos, Sketchnotes, COC Report   Announcing Berlin 2026 conference speakers