https://docs.kapa.ai/improving/writing-best-practices Skip to main content kapa.ai Logokapa.ai Logo kapa.aiDocumentationAPI reference Supportkapa.aiRequest Demo [122976076]Ask AI * Overview * Connecting Data Sources * Deploying Kapa * Analyzing Conversations * Improving Kapa + Troubleshooting and improving Kapa's answers + Conversation review best practices + Writing content for AI * Account Management * Security & Compliance * Developer Tools * * Improving Kapa * Writing content for AI On this page Writing documentation for AI: best practices Retrieval-Augmented Generation (RAG) systems like Kapa rely on your documentation to provide accurate, helpful information. When documentation serves both humans and machines well, it creates a self-reinforcing loop of content quality: clear documentation improves AI answers, and those answers help surface gaps that further improve the docs. This guide provides best practices for creating documentation that works effectively for both human readers and AI/LLM consumption in RAG systems. Many best practices benefit both simultaneously, often in complementary ways. Why documentation quality matters Documentation quality has always been important for helping users understand and use your product effectively. And it becomes even more important when AI systems use that same content to answer user questions. Poor documentation doesn't just frustrate human readers, it directly degrades the quality of AI responses, creating a compounding problem where bad content leads to bad answers. Understanding how AI systems process and use your documentation reveals why content quality is non-negotiable for good AI performance. How AI systems process your documentation Kapa works by finding relevant pieces of your content and using them to construct answers. The process involves three main components: * Retriever: Searches through your knowledge sources to find content that matches the user's question * Vector database: Stores your content in a searchable format that enables fast and accurate retrieval * Generator: A Large Language Model (LLM) that uses the retrieved content to create helpful responses Information flows through a specific process once you connect knowledge sources to Kapa: 1. Ingestion: Content is divided into chunks (smaller, focused sections) and stored in the vector database 2. Query processing: When users ask questions, the system converts their question into a searchable format 3. Retrieval: The system finds the most relevant chunks from your documentation 4. Answer generation: The LLM uses these chunks as context to generate a response In the steps that an AI takes to consume your content, there are some writing and structural patterns worth highlighting that can negatively impact how well your content is understood: * AI systems work with chunks: They process documentation as discrete, independent pieces rather than reading it as a continuous narrative * They rely on content matching: They find information by comparing user questions with your content, not by following logical document structure * They lose implicit connections: Relationships between sections may not be preserved unless explicitly stated * They cannot infer unstated information: Unlike humans who can make reasonable assumptions, AI systems can only work with explicitly documented information Documentation optimized for AI systems should ideally be explicit, self-contained, and contextually complete. The more a chunk can stand alone while maintaining clear relationships to related content, the better it can be understood by the AI. The more explicit and less ambiguous the information is, the better the retrieval accuracy is and the better equipped the AI becomes at answering questions confidently. While AI does work remarkably well with unstructured content, it's also true that information written and structured for with retrieval in mind can greatly improve the quality of an "Ask AI" interface to your knowledge sources. Why chunking is necessary Ideally, chunking would not be necessary, and the AI could continuously keep your entire knowledge base in context, all the time. Unfortunately, this is impractical. Not only due to token limits but also because LLMs perform significantly better when provided with optimized, focused contexts. A large or overly broad context increases the likelihood that the model overlooks or misinterprets critical information, resulting in reduced accuracy and less coherent outputs. Dividing documents into smaller, semantically coherent chunks enables retrieval systems to present the most relevant content to the LLM. This targeted approach significantly improves model comprehension, retrieval precision, and overall response quality. Quick tips to optimize your content Optimizing content for AI is similar in principle to optimizing content for accessibility and screen readers: the clearer, more structured, and more machine-readable your content is, the better it performs. Just as clear semantic structure helps accessibility tools parse content effectively, a clear structure significantly improves AI accuracy. This section outlines some actionable, practical improvements you can apply today to make your docs more machine-readable. Prioritizing these adjustments sets a strong foundation for addressing more nuanced content challenges, as discussed in the section Content design challenges for AI. 1. Use standardized semantic HTML For website sources, ensure correct and semantic use of HTML elements like headings (

,

), lists (