{
  "id": 8206407,
  "title": "Self-Improving Docs, Part 1: Automatically Turning Documentation Gaps Into Pull Requests",
  "url": "https://urgent.news/2026/09/18/self-improving-docs-part-1-automatically-turning-documentation-gaps",
  "topic": "tech",
  "section": "Tech",
  "published": "2026-09-18T08:28:01.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/meharshit/self-improving-docs-part-1-automatically-turning-documentation-gaps-into-pull-requests-2249"
  },
  "original_language": "en",
  "account": "Part 1: Automatically Turning Documentation Gaps Into Pull Requests\n\nThis article is the first installment of a series detailing self-improving documentation, where gaps are turned into pull requests. In the following part, the focus will be on the core functionalities of the documentation assistant, the feedback process, and the lessons learned during its development. Finally, the third part will cover the remaining part of the issue, including indexing, skills, and packaging for coding agents.\n\nTraditionally, the feedback loop for documentation was slow and depended on various dependencies. Readers encountering outdated pages typically opened a ticket in Slack, and the product team would relay the information back to the author. While this method still persists, there have been improvements in speed and audience.\n\nModern AI agents, unlike human readers, do not pause to verify the accuracy of outdated documentation. Instead, they treat the information as instructions and proceed with the outdated data. Consequently, outdated documentation is no longer just an editorial issue but a system problem.\n\nMintlify recently reported survey findings that align with the author's observations in their own work. Despite ongoing product changes, documentation still sometimes takes a week or more to reflect those updates. Only around a quarter of teams claim to have a same-day update. Simultaneously, many teams utilize AI agents to draft documentation updates, though few let these agents publish without human intervention.\n\nThe key takeaway is the recognition that documentation cannot keep up with product changes solely through manual writing and updating. Teams are leveraging agents for drafting, while still valuing human oversight to ensure accuracy. This realization led the author to the following problem: how to prevent missing and incorrect information from remaining in the documentation.\n\nThe author built a documentation assistant on their developer site, but chat alone was not enough to address the issue of missing and incorrect information. An assistant that cannot answer should not simply disappear into a log; it should identify the problem and self-update the documentation. The goal was to determine if a flagged issue by the assistant would be transformed into documentation improvement work. If the answer was a resounding no, the bot remained an answer-generating machine, unable to help close the documentation gap loop. However, if the answer was yes, it became a vital part of self-improving documentation.\n\nClosing the feedback loop implies that a reader asks a question on the documentation site, the assistant responds using the available documentation. If the response appears incomplete, missing, or incorrect, the data is captured as a point of improvement. This captured data could trigger an automated documentation job that drafts a change and creates a pull request. The author still reviews the PR, deciding whether to merge it or not; however, the process of identifying the gap and receiving feedback directly from the documentation site is a rapid and efficient way to improve the documentation.\n\nThere are two types of input into the system: automatic gap detection based on the assistant's response and human feedback from tags, escalations, and a feedback form. Both are valuable sources of information. The diagram illustrates the process, with the critical point being the final step: the draft is not published; instead, it is reviewed in a pull request, where a human decides which changes to incorporate.",
  "summary": "This blog is Part 1 of my series, Self-Improving Docs : Turning Gaps Into Pull Requests, on how I run documentation as a self-updating system. In Part 2 , I will go deeper into the docs assistant itself: how readers ask questions, how we handle feedback, and what we learned while building this experience. In Part 3 , I will talk about the other half of the same problem, which is making the docs…",
  "key_points": [
    "Self-improving documentation turns gaps into pull requests",
    "AI agents treat outdated docs as instructions, causing system issues",
    "Assistant identifies gaps, drafts changes, creates pull requests"
  ],
  "editors_take": null,
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}