# Optimizing Technical Docs for LLMs Learn from the best practices of companies like OpenAI, CircleCI, and Prisma on optimizing technical documentation for Large Language Models. by Emil Sorensen ## Overview ### Helpful Summary 1. Embrace Page Structure and Hierarchy 2. Segment Documentation by Sub-products 3. Include Troubleshooting FAQs 4. Provide Self-contained Example Code Snippets 5. Build a Community Forum 6. A Few More Practical Tips ### Helpful Summary - **Overview:** This article discusses best practices for optimizing technical documentation for Large Language Models (LLMs), drawing from experiences with over 80 technical teams. - **Why Trust Us:** We've worked with leading companies like OpenAI, CircleCI, Temporal, Mixpanel, and Docker to implement LLM-based systems for their developers. - **Why It Matters:** Properly structured documentation can significantly improve LLMs' ability to understand and respond to user queries, enhancing the overall developer experience. - **Action Points:** Implement clear hierarchies, segment documentation by sub-products, include troubleshooting FAQs, provide self-contained code snippets, build community forums, and follow additional practical tips. - **Further Research:** Consider signing up for a demo or reaching out to the kapa team for more insights on optimizing technical documentation for LLMs. ## 1. Embrace Page Structure and Hierarchy LLMs excel at navigating structured content and rely on context hints to understand the broader picture. A clear hierarchy of headings and subheadings on a page helps LLMs understand the relationships between different sections of your documentation. A great example of this is how Temporal structures its documentation for their SDKs. Take `Add a replay test` within the Java SDK, which is an important feature related to workflow execution. The hierarchy of the documentation is as follows: - Development - Java SDK - Develop for durability - Add a replay test This structure allows an LLM to more effectively navigate and understand the context when answering questions related to `replay tests` within the Java SDK. ## 2. Segment Documentation by Sub-products To avoid LLMs confusing similar offerings, such as cloud versus open-source versions, it's also helpful to ensure that good documentation hierarchy extends to the product level. We've seen that maintaining separate documentation for each sub-product can significantly improve the LLM's understanding of the context and the user's intent. A great example of this is how Prisma divides their documentation into their three main offerings: - `ORM`: A Node.js and TypeScript ORM (core product) - `Accelerate`: A Global database cache (newly released) - `Pulse`: Managed change data capture (early access) ## 3. Include Troubleshooting FAQs Troubleshooting sections formatted as Q&A are an effective source for LLMs as they mirror the questions users often ask, making it easier for LLMs to understand and respond to similar questions. OpenAI's documentation is a good example of this, particularly on their capabilities pages, where they have technical FAQs on the bottom of every page. ## 4. Provide Self-contained Example Code Snippets Including small, self-standing code snippets can be helpful, especially for products that rely on large and often complex SDKs or APIs. Mixpanel, for example, uses code snippets effectively across their documentation. For example, to increment numeric properties, they provide a code snippet to showcase the `mixpanel.people.increment` method. ## 5. Build a Community Forum This guide would be incomplete without mentioning the importance of building a community forum as a source for both developers and LLMs to get help on undocumented topics. A forum also works well as an interim solution for questions not yet covered in your official docs. ## 6. A Few More Practical Tips - Avoid storing docs in files: Keep relevant content directly in your docs. - Write text descriptions for images: Ensure information conveyed through screenshots is described in text. - Provide OpenAPI specs for REST APIs: Providing structured OpenAPI specifications makes it possible to leverage custom parsers. - Include example requests and responses: These give LLMs concrete examples. - Define specific acronyms and terms: Clarify all acronyms and specialized terminology within your documentation. - Include necessary imports in code examples: Ensure code examples can run without additional context. These tips can significantly improve LLMs' ability to understand and accurately respond to user queries. By following these guidelines, you can significantly enhance the usefulness of your technical documentation and sources for LLMs, ultimately improving the developer experience.