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