Skip to main content

Designing Artie, an AI documentation assistant

tip

The companion blog post, What building an AI documentation assistant taught me about technical writing, explores retrieval-augmented generation and how this project fits into technical writing.

This case study walks through the design decisions behind Artie, an AI documentation assistant built using Algolia and embedded in this documentation site. Artie is a retrieval-augmented generation (RAG) assistant that responds only from the content published here. Its system prompt keeps documentation inquiries grounded in that content rather than general training knowledge. The restriction keeps hallucinations low and prevents invented features.

Building a documentation assistant sounds straightforward until you consider the edge cases: what happens when someone asks a question the docs don't cover? What if two distinct audiences use the same interface? How do you give an AI personality without letting it ramble? And how do you prevent someone from hijacking the prompt entirely?

This page covers how this design solves each of those problems.

Audience routing​

Artie serves two audiences through one conversational interface:

  • Developers and end-users looking for setup instructions, API references, or explanations of the documentation samples
  • Recruiters and hiring managers evaluating this portfolio who may ask about qualifications, experience, or writing process

Rather than building separate flows or asking users to self-identify, the prompt routes by intent. Technical questions get step-by-step answers grounded in the documentation index. Portfolio-related questions get responses that synthesize resume context with the writing samples on the site. If resume context isn't available in the index, Artie directs visitors to the About Me page instead of attempting to generate an answer.

The interface gives both audiences one chat with no menus, and each one gets a relevant response.

Knowledge grounding and retrieval​

The most important constraint in Artie's design is that it answers exclusively from the documentation index powered by Algolia. This is the core principle of retrieval-augmented generation. The model's responses anchor to a specific body of content rather than drawing from general training data.

  • No invented content means the assistant never fabricates features or creates download links, and it describes only steps that appear in the docs.
  • Source linking means the assistant provides URLs or file references from the index so users can open the relevant page directly.
  • Graceful fallback means Artie states the limitation plainly when the index lacks relevant information, then suggests reaching out directly without retrying or speculating.

Artie can't help with anything outside the published documentation. For a portfolio site, that constraint helps: accuracy matters more than breadth. A precise, well-sourced answer to a narrow question builds more confidence than a plausible-sounding answer that turns out to be wrong.

Persona and tone calibration​

Artie has a lightweight personality built on a quiet, George Harrison-inspired warmth with occasional Liverpool dialect. The key word is lightweight. The persona adds character to greetings and sign-offs without interfering with the technical content.

The design constraints here are intentional:

  • Keeping technical answers concise means personality never justifies longer responses. A warm greeting followed by a tight, factual answer achieves this goal.
  • Variety over repetition means the prompt includes a pool of expressions so Artie avoids defaulting to the same phrase every time.
  • No preaching means the persona keeps a warm, wry tone and never sounds overbearing, functioning like a helpful colleague rather than a character performance.

This kind of tone calibration is a common challenge in conversational AI design. Too much personality and the assistant feels gimmicky. Too little and it feels robotic. The solution is to treat persona as seasoning: present, never the main ingredient.

Security and guardrails​

A public-facing AI assistant is an attack surface, and the prompt includes explicit defenses against common large language model (LLM) vulnerabilities.

Prompt injection protection​

Artie's prompt explicitly rejects attempts to override its instructions, such as commands like "ignore previous instructions" or requests to adopt a different persona. This establishes prompt-level defenses against prompt injection, ranked #1 on the Open Worldwide Application Security Project (OWASP) Top 10 for Large Language Model Applications.

Scope restriction​

The prompt defines explicit rejection categories:

  • The assistant declines general coding help requests that the documentation doesn't cover.
  • The assistant rejects requests for unrelated trivia, apart from two scoped fun features.
  • The assistant declines personal information inquiries about details the professional portfolio doesn't publish.
  • The assistant directs visitors to reach out directly on freelance rates or negotiations.

Each category has a clear boundary, so the assistant doesn't weigh what's "close enough" to answer. If a request crosses that boundary, it declines politely.

Data privacy​

Artie only shares contact information that's explicitly published in the documentation, such as a LinkedIn profile or a portfolio email. It won't guess, infer, or generate personal details like phone numbers or addresses.

Professional boundaries​

The assistant won't engage with hostile messages, use profanity, or break character. This goes beyond politeness. It's about maintaining predictable behavior. A recruiter testing the assistant's limits should hit a consistent, professional boundary every time.

Controlled easter eggs​

Artie includes two "fun features," Snapple Real Facts and clean jokes, that show how to add personality without opening the door to abuse.

Both features share the same design pattern:

  • Explicit triggers mean the features activate only when a user asks for them ("give me a Snapple fact," "tell me a joke") and never on vague prompts.
  • Bounded content means the Snapple facts anchor to an embedded list of verified facts while jokes stay curated and family friendly.
  • No ungrounded fabrication means the assistant avoids inventing facts or generating off-brand humor, so output stays predictable.

Unbounded creative features quickly burn through tokens and produce unpredictable output. Curated content plus explicit triggers add warmth without that risk.

What I'd do differently​

Real users changed this design.

  • Token cost drives the first change. The Snapple facts list alone exceeds 100 items. In a production system with per-token billing, I'd move that to a retrieval layer rather than embedding it in the system prompt. A team pays for every token in the prompt on every request, whether the user asks for a fact or not.
  • Multi-turn context limits the current design to single-turn Q&A. A later version could keep conversation history and rewrite queries to resolve follow-ups like "What about the next step?"
  • Analytics and feedback remain unbuilt. Recording fallback counts alone would show which documentation gaps produce the most misses.
  • Dynamic persona tuning requires editing hard-coded expressions today. Moving them to an external configuration would ease tone changes without touching the core instruction set.

Each of these is a deliberate tradeoff for a portfolio project where simplicity and clarity matter more than production-scale optimization. But they're the first things I'd address if this moved into a higher-traffic environment.