Why OSS maintainers need an AI chatbot on docs
If you maintain a popular open-source library, your inbox tells the same story every Monday. There are seven new GitHub issues filed over the weekend. You open the first one. It is a question, not a bug. The answer is on the Getting Started page, in the second code block. You paste the link, close the issue, and open the next one. It is the same question phrased differently. By the time you have triaged all seven, you have spent 45 minutes answering questions that the docs already answer. You have not written a single line of code.
This is the duplicate-issue tax. It scales with stars. A project at 1,000 stars gets a few duplicates a week. A project at 12,000 stars gets several a day. A project at 50,000 stars has a triage team or has given up on the issue tracker entirely. The work is not interesting, it does not move the project forward, and it cannot be batched because each issue feels personal to the person who opened it.
An AI chatbot trained on your docs sits between the user and the new-issue form. When the user lands on the docs site, has a question, and would normally hit the chat button on the navigation bar (or worse, click straight through to GitHub issues), the chatbot answers from the docs with a citation. If the chatbot cannot answer confidently, it tells the user where to go: GitHub Discussions for design questions, Stack Overflow for general usage, the issue tracker only for actual bugs. The chatbot does not replace your community channels. It routes traffic to the right one and intercepts the duplicates.
The persona: "Akira Tanaka" (sole maintainer, 12k stars)
Akira Tanaka maintains a React state-management library. Twelve thousand GitHub stars, 280 contributors on the all-contributors list, three steady weekly contributors who handle small pull requests, and Akira. The project has a documentation site built with Docusaurus, hosted on Vercel, with a custom domain. Docs are written in MDX so that interactive examples can render inline.
Akira has a day job as a senior engineer at a Tokyo fintech. He works on the library after 8 pm most weeknights and on Sunday afternoons. The library is not monetized; there is a small GitHub Sponsors page that brings in 240 dollars a month, which covers the Vercel Pro bill with a little left over. Akira does this because he likes it, not because it pays.
The thing that has slowly stopped being fun is the issue tracker. In a typical week, Akira gets 18 to 25 new GitHub issues. Of those, 11 to 15 are questions that the docs already answer. Roughly 4 are actual bugs. The rest are feature requests that need triage. Akira used to write a long, helpful reply on every question issue. Now he just pastes a link to the docs and closes it. He feels bad about that. He also does not have a better option, because writing the long reply at 11 pm on a Tuesday after work is not sustainable.
The duplicate-issue problem (60% of new GitHub issues are RTFM)
The number is not a guess. Run it yourself: open your project's closed-issues view, filter to issues closed without a code change, and divide by total closed issues for the same window. For most libraries between 5k and 50k stars, the ratio sits between 50 and 70 percent. Akira's number, when he ran it, was 63 percent.
Sixty-three percent. That is the share of triage time that produces no code, no documentation improvement, and no value beyond a single user being told to read the page they did not read. It is also, by Akira's rough estimate, about 8 hours a week of his life. Eight hours that could be spent on the v3 migration he keeps pushing back, or on the TypeScript inference fix that 200 people have upvoted, or on sleep.
The reason this is a problem and not a triviality is the asymmetry. The user who opens the issue spends 30 seconds typing their question into the new-issue form. Akira spends 5 to 10 minutes finding the right link, writing a polite reply, and closing the issue. Multiply by 12 a week and you have his entire Sunday afternoon. The new-issue form is friction-free for the asker and friction-heavy for the maintainer, which is exactly the wrong direction.
What ChatRaj does (answer FAQ-shaped issues from the docs before the user files)
ChatRaj sits on your docs site as a floating chat bubble. It trains on the docs by reading the sitemap.xml that Docusaurus, MkDocs, Nextra, and GitBook all generate by default. When a user lands on the docs from Google, hits the search box, types a question, and would otherwise click through to GitHub to open an issue, the bot answers from the docs with a citation back to the matched section.
The questions the bot catches are not exotic. They cluster into the same five buckets every OSS library sees. Installation: "does this work with pnpm?" "do I need a peer dependency on React 19?" "the install fails with a workspace error." Migration: "how do I move from v1 to v2?" "is there a codemod?" "does the new API still support X?" Usage: "how do I use selectors with TypeScript?" "what is the right way to derive state?" "how do I avoid re-renders?" Integration: "does this work with Next.js App Router?" "what about React Server Components?" "Remix?" Edge cases: "why is my store undefined on first render?" "why does the devtools extension not connect?"
For Akira's library, the bot's answers are grounded only in the docs site. There is no code execution, no test-running, no live evaluation of the user's bug report. The bot does not say "let me reproduce this" because it cannot. What it does, well, is recognize when a question matches a documented pattern and surface the answer with a citation. When the question is a real bug, the bot abstains and routes the user to file an issue with the bug template.
Linking docs + GitHub Discussions + Stack Overflow
A common mistake when adding chat to OSS docs is treating the bot as a replacement for community channels. It is not. The bot is the first stop for documented questions. Discussions, Stack Overflow, and the issue tracker still serve different jobs, and the bot should know about all three.
ChatRaj supports a routing-on-abstain configuration. When the bot has low confidence in its answer, the abstention message includes links to: the GitHub Discussions tab for design and architecture questions, the project's Stack Overflow tag for general usage questions, and the issue tracker's bug-report template for actual bugs. Akira configured his routing so that questions matching certain patterns ("why does my code crash" or "I get error X") route straight to the bug template, while questions matching "how do I" or "what is the right way" route to Discussions.
This routing matters because the bot's value is not just answering questions. It is keeping each question on the right channel. Bug reports in Discussions die unanswered. Architecture debates in the issue tracker derail bug triage. Stack Overflow questions on GitHub never get the SEO they would on Stack Overflow. The bot can see the question's shape before the user picks a destination, and it can guide them to the channel that will actually help them.
What ChatRaj does NOT do (no autonomous PR creation, no GitHub Actions integration, no code execution)
It is worth being explicit about the boundaries, because there is a class of "AI maintainer agent" tools that promise more. ChatRaj is not one of those tools. ChatRaj does not open pull requests autonomously. It does not run as a GitHub Action that closes issues based on heuristics. It does not execute user code to reproduce bugs. It does not have a sandbox where it tries fixes against your test suite.
The reason for those nos is simple: those features are not safe at the quality bar OSS users expect, and they push the maintainer's work in the wrong direction. An auto-closing bot that closes a real bug because it looked like a duplicate generates more triage work, not less. A PR-creating bot that drafts a "fix" without understanding the failure mode trains your contributors to expect AI slop in their review queue. A code-executing bot is a security problem the day it is misconfigured.
ChatRaj's scope is narrower and more defensible: be excellent at answering docs-shaped questions from the docs, and abstain everywhere else. The user still files the bug. You still review the bug. The bot's job is to make sure the bugs you review are bugs, not questions.
Setup on Docusaurus (most popular OSS docs framework)
Docusaurus is the most common framework for OSS docs at the 5k-stars-and-up scale, partly because Facebook ships it and partly because the MDX support makes interactive examples easy. The install is one script tag added to docusaurus.config.js under the scripts array. The script loads asynchronously and adds a floating bubble in the bottom-right of every page on the site.
The sitemap is automatic: Docusaurus generates /sitemap.xml at build time, and ChatRaj's crawler reads it on a schedule. Multi-version docs work too, because Docusaurus's versioned docs route includes the version in the URL, and the bot indexes each version separately. Akira's library has docs for v1, v2, and v3-beta; ChatRaj treats each as a separate source and routes questions to the version the user is currently reading.
Setup on MkDocs Material
MkDocs Material is the most common framework for Python OSS libraries. The install path is similar: paste the snippet into extra_javascript in mkdocs.yml, or into overrides/main.html if you prefer to keep config files clean. Material's mkdocs-material theme generates a sitemap automatically when the sitemap plugin is enabled, which is the default in recent versions.
For projects that use Read the Docs as the host, the same approach works because Read the Docs serves the rendered Material site. The script tag is part of the build output and runs in the visitor's browser on rtd.io subdomains the same as on a custom domain.
Setup on Nextra / GitBook
Nextra is increasingly popular for libraries that want React-flavored docs without the weight of Docusaurus. The install goes in theme.config.tsx under the head block, which Nextra injects into every rendered page. Sitemap generation is built into the Nextra docs theme.
GitBook is the most common hosted option, particularly for libraries that started with internal docs and migrated to a public knowledge base. The install path is GitBook's custom-script-injection feature on the paid plan, or the integration listing if GitBook has shipped a first-party integration for your bot vendor. ChatRaj's snippet works either way; it is one script tag.
Setup on a static-site docs (any HTML host)
For libraries with custom-built docs (Jekyll, Hugo, raw HTML, an Astro site), the install is the same one script tag pasted into the global layout template. The widget does not care about the framework; it cares about being loaded in the document's head or just before the closing body tag. As long as your site renders HTML in a browser, the bot can ride along.
The sitemap requirement is the only constraint. If your static site does not generate sitemap.xml, ChatRaj can crawl from a root URL by following internal links, but the sitemap path is faster, more reliable, and easier to debug when a page is missing from the index.
ROI: 30-50% reduction in duplicate issues; better-onboarded users
The honest expected outcome at 30 days is a 30 to 50 percent reduction in duplicate-issue volume. For Akira, that means his weekly question-issue count drops from 12 to roughly 6 or 7. The bot is not magic; some users will still file issues without checking the bot, and some users will ask the bot a question, get a confident answer, and file the issue anyway because they want a human to confirm. The deflection rate is not 100 percent, and any tool that claims it is is lying.
The second-order benefit is more interesting and harder to measure. New users who land on the docs and have a question answered by the bot in 15 seconds do not become users who churn after two days because they could not figure out the API. They become users who get to the second tutorial and then build something. Some of those users become contributors. None of that shows up in the issue-tracker math, but it shows up in your contributor list a year later.
OSS pricing: Free tier covers small projects (100 msgs/mo)
ChatRaj's free tier is 100 messages per month, which covers OSS projects with low to moderate docs traffic (say, under 200 weekly docs visitors). For a library at Akira's scale (12k stars, perhaps 1,500 weekly docs visitors), the free tier is not enough; the Pro tier at 29 dollars per month with 10,000 messages and no overage is the right fit. For very small projects at 500 stars and a handful of weekly visitors, the free tier may cover everything.
For OSS projects that fit the free tier comfortably but need a few features the paid tier includes (custom branding removal, multi-version support, the Unanswered tab, webhook events), the Pro tier is the same price as a few cups of coffee per month and tax-deductible if you run the project through a fiscal host like Open Collective. None of that is a hard sell; the page exists because OSS maintainers should know the free tier exists and is genuinely usable, not a bait pattern.