MCP Documentation Service

--- title: LLM-Optimized Documentation Template description: A template and guidelines for creating documentation specifically optimized for LLM consumption author: Claude date: '2024-03-20T00:00:00.000Z' tags: - template - llm - documentation - best-practices status: published order: 1 --- # LLM-Optimized Documentation Template This template provides a structure and guidelines for creating documentation specifically optimized for Large Language Models (LLMs) rather than human browsing. Following Andrej Karpathy's insight that "in 2025 the docs should be a single your_project.md text file that is intended to go into the context window of an LLM," this approach maximizes the utility of documentation for AI assistants. ## Purpose Traditional documentation is designed for human navigation through hyperlinked pages. LLM-optimized documentation consolidates all essential information into a single, well-structured file that fits within an LLM's context window, allowing the model to have complete understanding of your project without relying on chunked retrieval methods. ## Template Structure Below is a template you can use as a starting point for creating LLM-optimized documentation. Copy this structure and adapt it to your project. ```markdown # [PROJECT-NAME] Documentation [v1.2.3] CONTEXT-TYPE: Technical Documentation TOKEN-COUNT: ~150,000 LAST-UPDATED: YYYY-MM-DD STRUCTURE-VERSION: 1.0 ## METADATA PROJECT-NAME: Your Project Name VERSION: 1.2.3 REPOSITORY: https://github.com/username/repository PRIMARY-LANGUAGE: Language KEY-TECHNOLOGIES: Tech1, Tech2, Tech3 MAINTAINERS: Name1, Name2 LICENSE: License Type ## TABLE OF CONTENTS 1. [QUICK-REFERENCE](#quick-reference) (~5,000 tokens) 2. [CONCEPTS](#concepts) (~20,000 tokens) 3. [ARCHITECTURE](#architecture) (~15,000 tokens) 4. [API-REFERENCE](#api-reference) (~50,000 tokens) 5. [GUIDES](#guides) (~30,000 tokens) 6. [CONFIGURATION](#configuration) (~15,000 tokens) 7. [TROUBLESHOOTING](#troubleshooting) (~10,000 tokens) 8. [APPENDIX](#appendix) (~5,000 tokens) ## QUICK-REFERENCE [SECTION-ID:quick-reference] Most commonly needed information, commands, and patterns. ### Installation ```bash # Installation command npm install your-package ``` ### Common Usage Patterns ```typescript // Most common usage example import { something } from 'your-package'; const result = something(); ``` ### Key Concepts at a Glance - **Concept1**: Brief explanation - **Concept2**: Brief explanation - **Concept3**: Brief explanation ## CONCEPTS [SECTION-ID:concepts] Key concepts and terminology used throughout the project. ### [Concept1] [CONCEPT-ID:concept1] Detailed explanation of Concept1, including: - Purpose and importance - Core principles - Relationship to other concepts - Examples of using this concept RELATED-TO: [concept2, concept3] ### [Concept2] [CONCEPT-ID:concept2] Detailed explanation of Concept2... ## ARCHITECTURE [SECTION-ID:architecture] Overall system architecture and design. ### System Overview ``` ┌───────────────┐ ┌───────────────┐ │ Component A │─────▶│ Component B │ └───────────────┘ └───────────────┘ │ │ ▼ ▼ ┌───────────────┐ ┌───────────────┐ │ Component C │◀─────│ Component D │ └───────────────┘ └───────────────┘ ``` ### Component Details 1. **Component A** - Purpose: What it does - Responsibilities: What it handles - Dependencies: What it requires 2. **Component B** - Purpose: What it does - Responsibilities: What it handles - Dependencies: What it requires ### Data Flow 1. Request comes in through Component A 2. Component A processes and forwards to Component B 3. Component B performs operations and updates Component D 4. Component D notifies Component C 5. Component C generates response ## API-REFERENCE [SECTION-ID:api-reference] Complete API documentation. ### [FunctionName1] [API:function-name1] TYPE: Function DESCRIPTION: What this function does PARAMETERS: - param1 (type): description - param2 (type): description RETURNS: return type and description THROWS: potential errors ADDED-IN: v1.0.0 EXAMPLE: ```typescript // Usage example const result = functionName1('param1', 123); ``` ### [FunctionName2] [API:function-name2] TYPE: Function DESCRIPTION: What this function does ... ## GUIDES [SECTION-ID:guides] Step-by-step guides for common tasks. ### Guide 1: Accomplishing Task X [GUIDE-ID:task-x] Complete walkthrough of Task X: 1. First, install dependencies: ```bash npm install dependency-a dependency-b ``` 2. Create a configuration file: ```typescript // config.ts export default { setting1: 'value1', setting2: 'value2' }; ``` 3. Implement the main functionality: ```typescript // implementation steps... ``` 4. Testing your implementation: ```typescript // testing code... ``` COMMON-MISTAKES: - Forgetting to initialize X before calling Y - Using incorrect configuration parameters - Not handling errors from Z ## CONFIGURATION [SECTION-ID:configuration] All configuration options explained. ### Configuration File Format ```json { "option1": "value1", "option2": 123, "nestedOptions": { "subOption1": true, "subOption2": ["array", "values"] } } ``` ### Configuration Options [CONFIG:option1] TYPE: string DEFAULT: "default" REQUIRED: yes DESCRIPTION: Controls the behavior of X EXAMPLE: "custom-value" [CONFIG:option2] TYPE: number DEFAULT: 100 REQUIRED: no DESCRIPTION: Sets the limit for Y operations EXAMPLE: 500 ## TROUBLESHOOTING [SECTION-ID:troubleshooting] Common issues and their solutions. ### Error: "XYZ is not defined" [ERROR-ID:xyz-not-defined] CAUSE: This typically happens when the library is not properly initialized. SOLUTION: ```typescript // Make sure to import and initialize the library import { initialize } from 'your-package'; initialize({ option: 'value' }); ``` ### Performance Issues with Large Datasets [ISSUE-ID:performance-large-datasets] CAUSE: Default configuration is optimized for smaller datasets. SOLUTION: 1. Increase the 'batchSize' configuration option 2. Enable the 'caching' feature 3. Consider implementing pagination as shown below: ```typescript // Pagination example... ``` ## APPENDIX [SECTION-ID:appendix] Additional information. ### Version History - v1.2.3 (Current): - Added feature X - Fixed bug in Y - Improved performance of Z - v1.2.2: - Security fixes for A and B - Updated dependencies ### Related Resources - [Official Documentation](https://project-website.com/docs) - [GitHub Repository](https://github.com/username/repository) - [Community Forum](https://community.project-website.com) ### Glossary - **Term1**: Definition of Term1 - **Term2**: Definition of Term2 - **Term3**: Definition of Term3 ===== END OF DOCUMENTATION ===== ``` ## Guidelines for Implementation ### 1. Content Organization Principles - Use consistent heading levels (H1, H2, H3) to create a parseable hierarchy - Prefix sections with identifiers for easier reference - Include section IDs that can be referenced directly ### 2. Information Density Optimization - Prioritize information-dense, concise explanations over verbose descriptions - Use bullet points and numbered lists for series of related items - Eliminate redundant information that appears in multiple places ### 3. Reference System - Create a standardized cross-referencing system - Include a metadata section at the top with key definitions and terms - Group related concepts together to minimize context switches ### 4. Token Efficiency - Use standard abbreviations where clear (e.g., "config" vs "configuration") - Eliminate unnecessary words and phrases - Use tables for structured data to improve token efficiency ### 5. Context-Awareness Markers - Add section delimiters with unique patterns - Include relationship markers - Use explicit versioning notes ### 6. Specialized Sections for LLM Understanding - Add "REASONING:" blocks that explain the "why" behind design decisions - Include "COMMON-MISTAKES:" sections that highlight typical errors - Provide "EXAMPLE-FLOW:" sections that walk through complete processes ### 7. Token Budgeting - Core documentation: 60% of available tokens - Examples and tutorials: 25% of available tokens - Reference materials: 15% of available tokens ## LLM Context Window Considerations Different LLMs have different context window sizes. Adjust your documentation accordingly: | Model | Approximate Context Size | Documentation Guidance | |-------|--------------------------|------------------------| | Claude 3 Haiku | 48,000 tokens | Focus on core API and essential concepts | | Claude 3 Sonnet | 200,000 tokens | Complete documentation with examples | | Claude 3 Opus | 200,000 tokens | Full documentation with extended examples | | GPT-4 | 128,000 tokens | Comprehensive but prioritized content | ## Implementation in MCP Docs Service In future versions of MCP Docs Service, we plan to implement a tool that automatically generates LLM-optimized documentation from your existing docs structure, following the guidelines and structure outlined in this template. ## References 1. Andrej Karpathy's insights on LLM-optimized documentation 2. MCP Docs Service development roadmap 3. Documentation optimization research