Source material
A space written for colleagues answers customers in the wrong voice
Pointing an assistant at the internal knowledge base is the most tempting shortcut available, because the answers really are all in there. They are in there written for people who share your vocabulary, your access rights and your knowledge of who owns what, and every one of those assumptions turns into a specific kind of wrong answer once a customer is on the other end.
Why this one is harder than it looks
Internal writing is dense with shorthand that nobody thinks of as shorthand. Project codenames, team abbreviations, the internal name for a feature that is called something else in the product, the nickname for a process. Retrieval will happily surface a passage full of it, and the answer that comes back is either incomprehensible to the customer or, worse, uses an internal name for something confidently, sending them looking for a menu item that does not exist under that name.
Then there is the material that should never leave the building at all. Owner names and who to escalate to, links to internal tools, pricing thinking, notes about which customers are difficult, the reason a limitation exists that you would not put in writing publicly. None of it is marked as internal because the whole space is internal, so there is no signal for anybody to filter on. The boundary is the space itself, and pointing an assistant at it dissolves the boundary.
Drafts and archived pages are the quiet danger. A knowledge base accumulates half-finished pages, superseded procedures and things somebody wrote during a project that never shipped. Nothing in the text distinguishes those from the current, correct page on the same subject, and a well-written draft of a policy that was rejected reads exactly like the policy that was adopted. Both are in the space and both match the same question.
Nesting is the last structural problem. Internal spaces are organised as trees, and a child page inherits its meaning from its parent. A page titled Exceptions, sitting under a parent about one specific product line, is complete to anybody who navigated there and completely unmoored as a passage. The title carries no subject and the body assumes the parent, so the exceptions get quoted as though they applied to everything.
What it has to contain
Structure rather than wording. A passage pulled out of this document has to stand on its own, because that is the only form in which it will ever be read.
| A curated export, not a pointer at the whole space | A deliberately chosen set of pages, each reviewed for a customer audience. The unit of decision is the page, and somebody decided about each one. |
|---|---|
| Every internal term replaced with the customer-facing one | The name the customer sees in the product or on the invoice, used consistently. Internal names removed rather than explained, because an explained internal name still teaches the customer the wrong word. |
| No names, no internal links, no internal tools | Escalation paths, owner names and links to systems a customer cannot open are stripped, not merely hidden behind a login. Anything in an indexed page can end up quoted in an answer. |
| Each page carries its own subject in its first line | A page inherits nothing from a parent once it is a passage, so the subject, the product line and the scope all have to be in the page's own opening words. |
| One status only: current | Drafts, archived pages and superseded procedures are not in the exported set. Where two pages cover the same ground, exactly one is exported. |
The rewrite, in order
Export a curated subset instead of pointing at the space
Resist the instinct to connect the whole thing. Go through the space and choose the pages that answer questions customers actually ask, which is usually a small fraction of it, and export those. Everything else stays where it is, serving the colleagues it was written for.
Curating also solves the access problem, which is otherwise fatal. An internal space is behind a login, and a crawl of it does not see the content: it sees the sign-in page, over and over, and indexes that. What you get is not a partial import, it is a set of pages that all say the same thing about signing in, which will then be retrieved and quoted at customers.
There is a budget argument too. The per-assistant page allowance is set by plan, fifty on free, five hundred on Starter, five thousand on Growth and fifty thousand on Agency, and an entire internal space will consume a great deal of it with pages nobody will ever ask about. A curated set spends the allowance on the pages that earn it.
Translate the vocabulary out
Build a list of every internal term that appears in the exported pages: codenames, abbreviations, team names, the internal name for a feature the customer sees under a different label, the nickname for a process. Then replace every one with what the customer sees, in the product, on the invoice, or in the marketing.
Replace, do not annotate. A page that says the internal name followed by the public one in brackets is a page whose passages still contain the internal name, and a matcher does not know which of the two words in that sentence is the one it should be repeating back. If somebody genuinely needs the mapping, that belongs in a document that is not indexed.
Watch specifically for terms that mean something different outside. Internal writing is full of words like account, workspace, tenant and instance used with one precise local meaning and a completely different public one. Those produce answers that are grammatical, confident and about the wrong object.
Strip the internal apparatus
Remove owner names and escalation paths. A page that says ask the person who owns this area becomes an answer naming a colleague to a customer, which is at best awkward and at worst a privacy problem. It also names somebody who may have left.
Remove links to internal tools, tickets and dashboards. A customer given a link they cannot open is worse off than one given no link, because they now think they were shown a door and denied a key. Anything in an indexed page can be quoted, and a URL is one of the easiest things for a passage to carry.
Remove the reasoning you would not publish. Internal pages explain why a limit exists, which customers are on legacy arrangements, what the team thinks about a partner, what the plan is for a feature. All of that reads as authoritative when quoted, and none of it was written to be read by the person asking. Cut it rather than softening it.
Flatten the tree and give every page its own subject
Take each exported page and rewrite its title and opening line so that they carry the subject, the product line and the scope, with no help from the parent. A page called Exceptions becomes a page whose first line says which product's exceptions these are and when they apply.
Do the same inside the body. Internal pages lean on this product, the process above, and the team, all of which are anchored in a hierarchy that no longer exists once a page is a set of passages. Name the thing every time. It reads as repetitive to a colleague and it is exactly right for a reader who arrived with no path behind them.
Finally, deduplicate. Internal spaces accumulate several pages on the same subject written at different times by different people, and exporting all of them puts near-identical passages into the index competing with each other, where the one that wins is a matter of chance. Pick the correct one, export that, and leave the others internal.
What happens if you skip it
The answer that quotes a colleague to a customer
The characteristic failure of an internal space is an answer that is factually correct and unmistakably not meant for the person reading it. It names a member of staff to contact, uses a codename for a feature the customer has never seen, or links to a tool behind a login they do not have. Every detail is true, and the whole reply announces that the customer has been shown something internal.
The version that costs money is quieter. A superseded procedure and the current one are both in the space, both well written, both matching the question. The assistant answers from the old one and gives a customer a process that was replaced last year. Nobody notices, because the answer is plausible and the customer has no way to tell that it is out of date.
The most awkward is the unmoored child page. Exceptions to one product line's rules, retrieved for a question about a different product, quoted as though they were general. The passage is complete and confident. The scope it depended on was in the parent page's title, and the parent page's title was never part of the passage.
Check it against this
Before you index it
- Pages were chosen individually, not connected as a whole space
- No internal codename, abbreviation or team name survives
- No colleague is named and no internal link remains
- Every page states its subject and scope in its own first line
- Drafts, archived and superseded pages are excluded
- Exactly one page covers each subject
- Nothing exported would embarrass you if it were quoted verbatim
Questions
- Can I just crawl the internal space and let access control handle it?
- No, and it fails in a way that looks like it worked. The crawl obeys the login and gets the sign-in page instead of the content, so what lands in the material is many copies of a page about signing in. Those are then perfectly retrievable, which is how a customer ends up being told to log in to a system that is not theirs.
- How do I keep the exported copy in step with the internal one?
- Decide which copy is authoritative before you start. Either the exported version becomes the one you edit, with the internal page linking to it, or you set a review interval and re-export on a schedule. Two copies that both get edited will diverge, and the one the assistant reads is the one nobody remembers to update.
- What about pages that are half safe to publish?
- Split them. Take the part a customer can read and make it its own page with its own subject line, and leave the rest internal. Do not export a page with a section you are hoping will not be retrieved, because the whole page becomes passages and there is no way to mark part of one as off limits.
Keep reading
- How to upload a PDF manual so an assistant can answer from itA linked PDF is never crawled and a scanned one yields nothing. What to do about page furniture, columns, split tables and size.
- Using a staff handbook as a source without publishing the rest of itThe handbook answers customer questions in the second person, with pay and discipline bound in beside them. What to extract and what to leave.
- Turning saved support replies into material an assistant can answer fromThe replies your team already sends are the strongest material you own. How to strip the merge fields and separate policy from a one-off gesture.
- Every kind of source materialWhat to feed an assistant, and the surgery each document needs first.
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.