On the way to automate user manuals and knowledge bases

A developer proposes a Git-based workflow to automate user manuals and knowledge bases, using Markdown task files in a repo to generate release summaries and AI agents to update docs, with a CMS like Typemill for editor handoff. The approach aims to solve the maintenance burden of keeping user-facing documentation in sync with frequent software releases, avoiding the pitfalls of AI-generated docs that drift from actual product behavior.

On the way to automate user manuals and knowledge bases Docs as Code has quietly won for developer documentation. API references, SDK docs, changelogs – most of that now lives in a Git repo, gets reviewed in pull requests, and is built alongside the code it describes. User manuals, product documentation, and internal knowledge bases never really made that jump. They're still mostly living in Confluence, Notion, a shared Word document, or a PDF someone updates by hand. Not because Git is a bad fit for text, but because the people maintaining that content usually aren't developers. The deeper problem isn't the tooling gap, though. It's the maintenance load. Most software teams ship releases constantly, and every release potentially changes something a user-facing doc describes. Keeping that in sync by hand doesn't scale, and "just throw AI at it" is an easy way to end up with confident-sounding docs that quietly drift from what the product actually does. The obvious approach The straightforward idea: tag tickets with a release, have an AI summarize what changed from the ticket descriptions, then have it update the user docs – wherever they live, Google Docs included. This can work well, especially if tickets get tagged or updated once something is actually shipped rather than just when it's planned. But there's also a Git-based alternative that's arguably simpler, because it skips the ticket system for this purpose entirely and keeps the source of truth next to the code itself. A more code-centric alternative Here's a pattern that I use for some time now: instead of writing tasks in a ticket system, I write them as Markdown files that live in the repo itself, next to the code: /ai /tasks /fix-abc.md /add-export-pdf.md Each file describes a task and, once finished, what was actually done to complete it. In practice this has already replaced most of what used to go into a ticket system or a Confluence page for architecture notes – the task and its resolution live where the code lives, and stay accurate because they're written by whoever actually did the work, not planned in advance and left stale. From there, generating a release summary is straightforward: collect the finished task files tagged for a release, and you have a much more reliable source than ticket text. If your user documentation similar to the code documentation also lives in a repo as Markdown, an AI agent can update the relevant doc pages directly from a finished task – either immediately after the task is done, or in a batch when a release goes out. Handing off to editors Not everything belongs in that automated pass. Screenshots, tone, context for less technical users, sections that have nothing to do with a specific code change – that's editorial work, and forcing it through Git is exactly the barrier that kept user documentation out of Docs as Code https://typemill.net/knowledge-hub/docs-as-code in the first place. So the developer-driven updates need to land somewhere non-technical editors can pick them up without touching Git: a CMS, synced to the repo. Editors get the AI-drafted changes as a starting point, refine them with their own AI tooling, and add whatever doesn't come from the code at all. php flowchart TD Tasks "/ai/tasks/ .md" -- Agent1 AI coding agent Code Code changes -- Agent1 Agent1 -- Docs User docs in repo with Markdown Docs <-- |git sync| CMS CMS for editors CMS -- Agent2 Editorial AI assistant Agent2 -- CMS CMS -- Web Website CMS -- PDF PDF export CMS -- Ask Ask-the-docs I have built one version of this with Typemill https://typemill.net and GitSync https://plugins.typemill.net/gitsync : a self-hosted, database-free CMS connected to a Git repo via a plugin. From the synced content, Typemill can publish a website with access control, produce a PDF, translate content, and – since it can run against an AI service of your choice, including local models – offer a simple "ask the docs" search on the published site. None of this requires Typemill specifically, and it probably could be built on top of an MCP-based setup instead. Docs as Code just felt like the more natural fit here, since the task files, the code, and the docs already live in their repos. What's still missing Two things, honestly: Concurrent editing at scale. GitSync is a first release. It just blocks the sync if a file has been changed in the CMS and in GitHub at the same time, but it doesn't really solve merge conflicts if several people are working on the same documentation at once. That's a real limitation once a setup like this grows. Screenshots. Screenshots of the software interface are still mostly manual work. Automating "this screenshot is now outdated because the button moved" is a harder problem than syncing text, and I don't have a good answer yet. If you're solving either of those in a different toolchain, or handling the ticket-vs-task-file tradeoff differently, I'd be curious how.