Writing Documentation for LLMs
When to Use
- Creating documentation, guides, or reference materials
- Writing API docs, feature specs, or knowledge bases
- Structuring information for LLM discovery
- Evaluating documentation quality and comprehensiveness
Core Principles
Assume Competence
LLMs already know fundamentals. Only add information they don’t have. Every section should justify its token cost.
Verbose (~150 tokens):
PDF (Portable Document Format) files are a common file format that contains text, images, and other content. To extract text from a PDF, you'll need to use a library. There are many libraries available for PDF processing...Concise (~50 tokens):
Use pdfplumber for text extraction:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
### Match Specificity to Task Fragility
**Narrow instructions** (low freedom) when:
- Operations are error-prone or destructive
- Consistency is critical
- Exact sequence required
**General guidance** (high freedom) when:
- Multiple approaches are valid
- Context determines best path
- Heuristics guide the approach
## Structure Best Practices
### Progressive Disclosure
Organize like a table of contents. Main file provides overview; detailed materials referenced only when needed.
- Main file: high-level guide with references (<500 lines)
- Reference files: one per domain/topic
- Avoid nested references (file A → B → C)
### Table of Contents
For files >100 lines, include TOC so LLMs see full scope even with partial reads.
### Consistent Terminology
Choose one term and use it throughout:
- Always "API endpoint" (not "URL", "route", "path")
- Always "field" (not "box", "element")
- Always "extract" (not "pull", "get")
## Content Patterns
### Descriptions: What + When
Enable discovery with concrete capability + context:
**Good**: "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction."
**Bad**: "Helps with documents"
### Examples Over Explanations
Show concrete input/output examples before abstract descriptions.
### Workflows with Clear Steps
Break complex operations into sequential steps. Use checklists for complex workflows.
### Feedback Loops
Use validator patterns for quality-critical tasks:
1. Make edits
2. **Validate** — Run validation
3. If validation fails — Review, fix, retry
4. **Only proceed when validation passes**
## Anti-patterns to Avoid
- **Too many options**: Present single recommended approach, alternatives only if necessary
- **Deeply nested references**: Keep one level deep from main file
- **Vague terminology**: Use specific, discoverable language
- **Windows-style paths**: Always use forward slashes (e.g., `scripts/helper.py`)
- **Time-sensitive information**: Use "Old patterns" sections with details collapsed