An Internal Documentation Assistant for Onboarding New People
Every new joiner turns up with the same questions. Every organisation answers them badly. Not because the answers are missing, but because they sit scattered across a wiki, a shared drive, three Slack channels and a PDF someone exported back in 2023. We build retrieval augmented assistants for exactly this gap: an AI that answers from your own documents and shows you where the answer came from.
Why Onboarding Breaks Down in the First Weeks
A newcomer cannot tell which document is authoritative, so they ask a colleague instead of searching. The cost lands on senior people who get interrupted, not on the person asking. Keyword search fails them too, because they do not yet speak the internal dialect - they type "vacation" while the policy says "annual leave". What they need is an answer in plain language, with a visible pointer to where it came from.
What a Retrieval Augmented Assistant Actually Does
The model answers from your documents rather than from whatever it absorbed during training. The pipeline runs in order: split documents into passages, embed them, retrieve the closest matches to the question, then hand those passages to the model as context. Each answer carries its source passage, verifiable in one click. And when nothing relevant comes back, the correct behaviour is to say so. A wrong answer with a visible source is correctable. One without a source is not.
Choosing the Content That Goes In
Start with the handful of documents people ask about in week one, not the full archive. A typical first set covers environment setup, access requests, the deployment procedure, the team ownership map, and holiday and expense policy. Duplicated files are the main source of contradictory answers, so deduplicate before ingesting.
What to leave out initially:
- Superseded policies still sitting next to their replacements
- Drafts nobody approved
- Personal notes and scratch documents
- Meeting minutes that record no decision
- Anything nobody would defend as current
Tip: an assistant answering from a stale document exposes a documentation problem you already had. Fix the document, not the retrieval.
Cloud or Your Own Infrastructure
Internal documentation holds client names, salaries, credentials and security procedures, so where it sits is a real decision. Cloud is faster to start and lighter to operate, with strong models available immediately. On-premise or a private VPC keeps documents and embeddings inside the customer's network, which some contracts and regulators require. Settle three questions first: who can read the index, where question logs live, and what happens to a document after deletion at the source. Hybrid splits work well - open handbook content in the cloud, restricted material self-hosted.
Permissions, or Why the Index Needs to Know Who Is Asking
A single flat index leaks. A junior developer should never receive board deck contents just because the passage matched semantically. Filter at retrieval time using the asker's group membership, not by post-processing what the model already wrote. Keep those permissions synchronised with the source system instead of maintaining them by hand in a second place. Question logs deserve the same care, because people ask about parental leave and notice periods.
Tip: test with a deliberately restricted document and a low-privilege account before anyone else gets access.
Measuring Whether It Helps
Assemble a small evaluation set of real onboarding questions with known answers before launch. Check retrieval separately from generation: if the right passage was never fetched, no model will rescue the answer.
- Questions that returned nothing
- Answers people marked as wrong
- Repeat questions on one topic
- Documents never retrieved at all
Questions without a good source become a backlog for the documentation team, which is half the value here. Usage volume proves little. Fewer repeated Slack questions is the outcome that matters.
Rolling It Out Without Losing Trust
Pilot with one team and one cohort of joiners, then widen once the answers hold up. Name an owner for content freshness - without one, the index rots within a quarter. Say plainly what the assistant does not cover, so people know when to ask a human instead. Wire ingestion directly to the document source so updates propagate automatically rather than through manual re-uploads. Trust disappears fast and comes back slowly, so a narrow assistant that is right beats a broad one that guesses.
FAQ
How is this different from search in our wiki?
Search returns documents ranked by keyword match and leaves the reading to you. The assistant answers the question in words and points at the passage it used, which matters most for someone who does not yet know your terminology.
Can it run without sending our documents to an external provider?
Yes. The whole stack, model included, can run on your own infrastructure when the data cannot leave the network.
What happens when the answer is not in the documents?
It should state that nothing relevant was found and route the question to a person. That gap then belongs on the documentation backlog.
Summary
Onboarding is a retrieval problem more than a writing problem - the answers usually exist somewhere already. Grounded responses with visible sources keep the system auditable and correctable. Three decisions determine whether it is genuinely usable: where you deploy it, how you filter by permission, and which content you curate in. Start narrow, measure against real questions, and treat every unanswered one as documentation work.
