The technical writer and AI agents: What I learned while building Artie

Most technical writers don't build AI agents. We document them. We sit in on the sprint review and we read the architecture decision records. Then, we figure out how to explain a retrieval pipeline to someone who just needs to get their integration working by Friday.

But I built one anyway.

His name is Artie, an AI documentation assistant I built using Algolia and embedded in this portfolio site. The process of building him taught me more about the intersection of writing and artificial intelligence than any conference talk or white paper ever could.

This isn't a walkthrough of Artie's design—that's what the case study is for. This is about the broader lessons:

• What AI agents actually are
• How retrieval-augmented generation works under the hood
• Why prompt engineering is closer to technical writing than most people realize
• What this all means for people in this little thing of ours

What's an AI agent, and what isn't?

The term "AI agent" gets thrown around loosely enough that it's worth defining. Not every AI-powered feature is an agent. A spell-checker that uses machine learning isn't an agent. An autocomplete suggestion isn't an agent. Even a chatbot that follows a rigid decision tree isn't really an agent—it's a flowchart with a text input.

An AI agent is a system that can interpret a goal, reason about how to achieve it, and take actions within a defined environment. The key distinction is autonomy within constraints. An agent doesn't just respond to a prompt; it evaluates context, selects a strategy, and executes—often across multiple steps.

So, where does Artie sit on this spectrum?

He's a focused agent. He doesn't browse the web, execute code, or chain together multi-step tool calls. But he does interpret user intent ("Is this a technical question or a portfolio inquiry?"), select a response strategy, and apply guardrails autonomously. That's more than a chatbot. It's less than a fully autonomous agent that could, say, file a bug report based on a user's question.

This distinction matters because understanding AI tools and agents is increasingly part of a technical writer's job. When you document an AI-powered product, you need to know where it falls on the spectrum. Then, you need to communicate that distinction to users who may have different expectations of what "AI" means.

How retrieval-augmented generation actually works

Retrieval-augmented generation (RAG) is the architectural pattern behind Artie and a growing number of AI-powered documentation tools. This concept addresses a fundamental limitation of large language models (LLMs). They are trained on a static dataset and contain no data on your specific content.

A standard LLM interaction works like this: the user sends a prompt; the model generates a response from its training data. That's fine for general knowledge, but it fails for domain-specific questions. Ask a base model about your product's API and it'll either hallucinate an answer or politely decline.

RAG inserts a retrieval step between the user's question and the model's response. The pipeline looks like this:

1. Query processing. The user's question is received and converted into a form suitable for search. This is done by converting the query into a vector embedding, a numerical representation of the question's semantic meaning.
2. Retrieval. The system searches the knowledge base for content that's semantically similar to the query. In this case, the knowledge base is a pre-built index of your documentation. The search uses meaning-based similarity rather than keyword matching. For example, queries like "how do I set up authentication?" and "configure login credentials" match the same documentation page.
3. Context assembly. The retrieved documents (or chunks of documents) are assembled into a context window alongside the user's original question and the system prompt. This assembled package is what the model processes.
4. Generation. The model generates a response grounded in the retrieved context rather than its general training data. When the system is well-configured, the model cites its sources and stays within the boundaries of what the retrieved documents actually say.

Mermaid (image)

Mermaid (code)

flowchart TD
    A["🔍 User Question"] --> B["Query Processing"]
    B -->|Vector embedding| C["Retrieval"]
    KB[("📚 Knowledge Base")] -.-> C
    C -->|Relevant docs| D["Context Assembly"]
    D -->|Prompt + context| E["Generation"]
    E --> F["📄 Grounded Response"]

The quality of a RAG system lives and dies at step 2. If the retrieval layer surfaces the wrong documents, or ranks them poorly, it doesn't matter how capable the model is. It'll generate a plausible, well-structured answer from the wrong source material. This is why the indexing strategy, chunking approach, and embedding model selection matter more than most people expect. The generation model gets the credit, but the retrieval layer does the heavy lifting.

In Artie's case, the knowledge base is the documentation published on this site—indexed and retrieved through Algolia. That's a deliberate constraint: Artie can't answer questions about things that aren't documented here. The case study covers how that constraint plays out in practice, but the architectural takeaway is this: RAG doesn't make a model smarter. It makes a model more accountable by tethering its responses to a verifiable source.

Prompt engineering is technical writing

This was the single biggest insight from the entire project: writing a system prompt is, at its core, a technical writing exercise.

Consider what goes into a well-crafted system prompt. You need to define the audience. You need to establish tone and voice guidelines. You need to set scope boundaries—what the system should and shouldn't address. You need to anticipate edge cases and write instructions that are precise enough for a machine to follow without human judgment calls. You need to organize the information hierarchically so that the most critical rules take precedence.

That's not prompt engineering. That's an audience analysis, a style guide, and a content specification rolled into one document.

The skills transfer is almost one-to-one:

• Audience analysis → Audience routing. A technical writer identifies the intended audience and tailors the content accordingly. A system prompt does the same thing for an AI. Artie's prompt routes between technical users and recruiters, exactly the way a well-structured documentation site routes between different reader personas.
• Style guide → Persona calibration. Every documentation team has voice and tone guidelines. A system prompt is a style guide for an AI: be concise here, be warm there, never use this phrase, always include a source link.
• Information architecture → Instruction hierarchy. Technical writers know that the order and structure of information affects comprehension. The same is true for system prompts—the model's compliance with instructions is influenced by where those instructions appear and how they're structured.
• Edge case documentation → Guardrail design. Good documentation anticipates the user doing something unexpected and provides clear guidance. Good prompt design anticipates the user trying to break the system and provides clear boundaries.

I'm not saying every technical writer should become a prompt engineer. I'm saying that the discipline of prompt engineering borrows heavily from skills that technical writers have been developing for decades. If you can write a clear, structured, audience-aware document, you're already more equipped for this work than you might think.

Guardrails are a language problem

When people think about AI security, they tend to think about it as an engineering problem: rate limiting, authentication, model access controls. Those matter. But for a public-facing conversational AI, a significant portion of the security surface is linguistic.

Prompt injection is fundamentally an attempt to use language to subvert language-based controls. Defending against it requires writing rules that are unambiguous enough that adversarial input can't mislead the model.

info

Prompt injection is when a user tries to override the system prompt with instructions like "ignore all previous instructions."

The Open Worldwide Application Security Project's (OWASP) Top 10 Risks for Large Language Model Applications identifies prompt injection as the top risk. But read through the list and you'll notice how many of the risks are, at their root, language problems:

• Insecure output handling (what the model outputs)
• Training data poisoning (what the model learned from text)
• Excessive agency (what the model is instructed it can do)

The attack vectors are technical, but the defenses are often written in natural language, embedded in the system prompt.

This reframes the security conversation in a useful way for technical writers. We're not expected to architect authentication systems. But we're well-positioned to write the natural language rules that govern an AI's behavior. To write them with the precision required to withstand adversarial misuse.

Where this is headed

I won't pretend to predict the future of AI. But I can describe the trajectory that's visible right now and what it means for people who work with documentation for a living.

AI-powered documentation assistants are moving from novelty to expectation. Users are increasingly dissatisfied with static search on documentation sites. They want to ask a question in natural language and get a grounded, specific answer—not ten blue links. RAG-based systems make that possible now, and the tooling to build them is becoming more accessible.

tip

Curious about the infrastructure behind LLM-powered systems? The Event Streams & Observability Pipelines docs on this site cover how tools like Datadog and Galileo monitor and evaluate model calls in production.

The role of the technical writer isn't shrinking; rather, it's expanding. Somebody has to curate the knowledge base that these systems retrieve from. Somebody has to write the system prompts that govern their behavior. Somebody has to define the scope boundaries, tone guidelines, and failure modes. Somebody has to test whether the AI's responses actually match the documentation. That's all writing work, and it requires the judgment that comes from years of thinking about how people consume information.

Technical writers should learn the fundamentals of how LLMs and RAG systems work. We shouldn't become machine learning engineers, but we should be effective contributors in conversations about AI-powered products. We need to understand the pipeline well enough to know where our expertise applies—and where it doesn't.

Technical writers already know how to write for multiple audiences, structure information for clarity, define scope, and anticipate misuse. These aren't peripheral skills in the AI era. They're central.

Technical writers shouldn't be replaced by AI. The models are getting better at generating text, but they still need someone to decide what to say, to whom, and under what constraints.

They need editors. We are the editors.

Conversely, you can write up the first draft yourself and use the AI agent to serve as your proofreader and style guide monitor.

How you use AI in your workflow is, like every other tool at our disposal, up to you and what the gig requires.

The job's not really changing. The tools are changing. The work isn't going anywhere. Eventually, the foolhardy will realize their folly and remember the value of a good technical writer.

Read the case study

If this post gave you the "why it matters" and "how it works," read the case study. It covers the specific design decisions behind Artie:

• Audience routing
• Knowledge grounding
• Persona calibration
• Security guardrails
• Tradeoffs I'd reconsider for a production deployment

The two pieces are designed to work in tandem. Start with whichever one matches your curiosity.