Discourse and developer tools company
The forum is not your documentation and must not be read as it
Putting an assistant on a community is the easy part. Discourse has a field made for markup at the end of the body and a component system that keeps your addition out of the theme's way. The decision that matters here is what it reads, because a busy forum is the largest pile of writing your company has and almost none of it was written by your company.
Why this pairing is its own job
The Discourse install guide covers the tag, and the developer tools company guide covers what the assistant has to know. What follows is the part that belongs to neither.
- Threads are member written. An assistant answering from them puts somebody's guess into a reply carrying your name and your logo, with a citation that makes it look checked by you.
- Accepted answers are the most tempting material and the most version skewed. A solution that worked two releases ago is marked as correct, which is exactly the signal that gets it retrieved ahead of the current documentation.
- The documentation and the community are two origins. A docs subdomain and a community subdomain are unrelated to a browser and to the allowlist, and the install on each is a different job in a different system.
- A private or partly restricted community shows an unauthenticated crawl a sign in screen, so the material you assumed you had turns out to be one page of it.
What changes about the install here
<script src="https://cdn.askably.xyz/w.js" data-key="pk_live_YOUR_KEY" defer></script>The tag is the same one on the Discourse guide. Everything below is about where it goes on a developer tools company site specifically.
Component on the forum, and a separate install on the documentation
On the forum, the component route is the one that survives an upgrade and the body field on it is described for exactly this purpose. That part is covered on the Discourse install page and nothing about it is specific to a tools company.
What is specific is that the forum is the second install rather than the first. The documentation site holds the answerable material, sits on its own address, and is built on something else entirely. Do that one first, get the corpus right there, then decide whether the forum shares its key.
Same key or a different one
The same key means one assistant and one corpus, so a member on the forum gets documentation answers, which is usually what they wanted when they opened the panel. It also means the forum address joins the documentation address on the allowlist.
A different key lets you give the forum assistant a narrower corpus and a refusal that points at the community rather than at support. Worth it where your forum has its own conventions and its own moderators, and it is one more assistant to keep current.
Decide what the crawl is allowed to reach
Point it at the reference documentation, the changelog, the migration guides and the error reference. Leave the forum out of the material, including the public parts of it.
This is not a slight on the community. It is that nothing in the retrieval step distinguishes a maintainer's reply from a confident member's, and neither of those is your documentation. Where a thread contains an answer worth giving in your name, the answer belongs in the documentation, and moving it there is work that pays twice.
The exception worth making is a category your own team writes and dates, such as announcements. Even then it is worth checking how old the oldest entry is before it joins the corpus.
Where the answerable material lives
| Reference documentation, labelled by release | The label is the point. A corpus mixing three majors with no version marker returns a signature removed two releases ago, and a reader on a forum has no way to tell which release the answer came from. |
|---|---|
| Migration guides and deprecation notices | The highest support value material you have, and the material that answers the questions your forum fills up with after every release. Index them with their dates and their removal timelines. |
| The error and status code reference | Developers paste the error rather than describing the concept. If your error strings appear nowhere in your documentation, the most common query on both sites is one nothing in the corpus can answer. |
| Forum threads | Excluded on purpose. Member written, unversioned, and often correct only for a release that is gone. The community is where people talk to each other, not where your product answers in its own voice. |
The first thing to get right
Index the documentation, exclude the forum, then install on both sites with the same key.
It gives a member on a thread the documented answer with a citation they can check against their own version, which is the thing forum search never does well. Every other choice on this page can be revisited later. The corpus decision cannot, because by the time you notice it was wrong somebody has already acted on a stranger's answer from two years ago.
The failure that belongs to this combination
It answered in your name with a workaround a member posted years ago
The mechanics are ordinary. Somebody asks about an error, the closest match in the material is a long thread with an accepted answer, and the reply comes back specific, plausible and citing a page on your own community.
The reader cannot tell the difference. The citation points at your domain, the answer arrives in the assistant's voice, and the workaround it describes disables a check that stopped being safe two releases ago. Support then spends a week on the consequences of an answer nobody at the company wrote.
This is why the corpus decision comes before the install decision on this pair. Everything else here is a preference between two workable options. That one is the difference between a useful assistant and a liability wearing your logo.
Before you go live
- The origin the page is served from has to be on the allowlist for that assistant, or nothing renders and the browser console says which origin was refused. An apex domain and its www are two different origins to a browser, so list both, along with any staging or preview host you want it to work on.
- Open the site as a visitor would, on the pages a developer tools company visitor actually lands on, and ask it something only your own material could answer. A widget that renders is not the same as a widget that has read anything.
Questions
- Does it post in threads?
- No. It is a panel a member opens, so it never appears in a topic, never replies to anybody publicly and never touches your moderation queue. Worth saying to your moderators before you switch it on, because that is the first thing they will ask.
- Our community is members only. Can it read it?
- An unauthenticated crawl reaches the sign in screen and stops, so no. That is fine here, since the forum was never the corpus you wanted. Point it at your public documentation and treat the private discussion as out of scope rather than trying to force it in.
- Discourse blocked the script. Which problem is it?
- Read the console message. A policy problem names a directive and is Discourse's own content policy at work, which is why the theme component field is the supported route. A refused origin names your forum address instead, and adding that origin is the entire fix.
Keep reading
- Installing on DiscourseCreate a theme component under Appearance, open Edit Code, and paste the tag into the body field so an upgrade cannot lose it.
- Everything for a developer tools companyOn a docs site an assistant competes with search, not a phone line. Version skew, deprecations and error strings decide whether it earns its place.
- What happens to the assistant when each release is its own MkDocs buildEvery release is deployed as its own static copy. Older ones were built before you added the override, so they carry no tag and cannot get one.
- Translated Starlight documentation and the duplicate pages it puts in the corpusUntranslated pages are served in the default language under every locale URL, so one page reaches the index as several near identical documents.
Try it on your own material
Upload a document or point it at your site, paste one line of HTML, then ask it something only your business could answer.