evidence-citation

Evidence Citation Patterns

Guidelines for creating evidence-backed technical documentation. Every significant claim should be traceable to actual source code.

Core Principle

Never make claims without evidence. Documentation that isn't grounded in actual code becomes stale and misleading. Always cite your sources.

Citation Formats

Single File Reference

Use when pointing to a specific file:

The system uses FastAPI for the REST API (see `app/main.py`).

Line Number Reference

Use when pointing to a specific location:

Authentication is handled by the `verify_token` function (see `auth/jwt.py:42`).

Line Range Reference

Use when referring to a block of code:

The checkout workflow is implemented in `services/checkout.py:15-89`.

Pattern/Glob Reference

Use when referring to multiple files:

All API routes follow RESTful conventions (see `routes/**/*.ts`).

Directory Reference

Use when referring to a module or component:

User management is handled by the auth module (see `src/auth/`).

Citation Levels

Level 1: Inline Citation (Minimum)

For quick references where the reader can easily find the code:

The system uses PostgreSQL for persistence (see `docker-compose.yml`).

Level 2: Citation with Context (Recommended)

Include brief context about what to look for:

Rate limiting is configured at 100 requests per minute (see `middleware/ratelimit.ts:23` — the `RATE_LIMIT` constant).

Level 3: Citation with Code Sample (Best)

Include actual code for critical documentation:

The system uses FastAPI for the REST API (see `app/main.py`):

\`\`\`python
from fastapi import FastAPI
app = FastAPI(title="MyAPI", version="1.0.0")
\`\`\`

When to Use Each Level

Situation	Citation Level	Example
Well-known patterns	Level 1	"Uses React hooks (see hooks/)"
Configuration values	Level 2	"Timeout set to 30s (see config.ts:15 — REQUEST_TIMEOUT)"
Critical architecture	Level 3	Full code sample with file reference
Security mechanisms	Level 3	Full code sample showing implementation
Complex algorithms	Level 3	Full code sample with explanation

Evidence Gathering Process

Step 1: Identify Claims

List all factual statements you're making:

• "The system uses X framework"
• "Authentication works via Y mechanism"
• "Data flows from A to B"

Step 2: Find Evidence

For each claim, locate the source code that supports it:

# Search for framework usage
grep -r "from fastapi" --include="*.py"

# Find configuration
grep -r "DATABASE_URL" --include="*.env*"

# Locate specific functions
grep -rn "def authenticate" --include="*.py"

Step 3: Verify Accuracy

Before citing, verify:

• File exists at the stated path
• Line numbers are current
• Code sample matches actual file content
• Claim accurately reflects what the code does

Step 4: Add Citations

Insert citations using appropriate level based on importance.

Common Citation Patterns

Architecture Claims

The application follows a layered architecture:
- **Presentation layer**: API routes (see `routes/`)
- **Business logic**: Service classes (see `services/`)
- **Data access**: Repository pattern (see `repositories/`)

Technology Claims

The frontend is built with React 18 and TypeScript (see `package.json:12-15`):

\`\`\`json
{
  "dependencies": {
    "react": "^18.2.0",
    "typescript": "^5.0.0"
  }
}
\`\`\`

Configuration Claims

The API rate limits requests to 1000/hour per IP (see `config/ratelimit.ts:8`):

\`\`\`typescript
export const RATE_LIMIT = {
  windowMs: 60 * 60 * 1000, // 1 hour
  max: 1000
};
\`\`\`

Workflow Claims

The checkout process follows these steps (see `services/checkout.ts:45-120`):
1. Validate cart items (`validateCart()` at line 48)
2. Calculate totals (`calculateTotals()` at line 62)
3. Process payment (`processPayment()` at line 78)
4. Create order (`createOrder()` at line 95)

Anti-Patterns to Avoid

Vague References

# Bad
The system handles authentication.

# Good
Authentication uses JWT tokens validated by middleware (see `middleware/auth.ts:15-30`).

Outdated Line Numbers

# Bad (if code has changed)
See `auth.ts:42` for the login function.

# Better (more resilient)
See the `handleLogin` function in `auth.ts`.

Missing Critical Evidence

# Bad
The API is secure.

# Good
The API implements security measures including:
- JWT authentication (see `middleware/auth.ts`)
- Rate limiting (see `middleware/ratelimit.ts`)
- Input validation (see `validators/`)
- HTTPS enforcement (see `server.ts:12`)

Invented Code Samples

# Bad (making up code)
\`\`\`python
# This is how it probably works
def authenticate(user):
    return check_password(user)
\`\`\`

# Good (actual code from repo)
\`\`\`python
# From auth/service.py:23-28
def authenticate(credentials: LoginCredentials) -> AuthResult:
    user = self.user_repo.find_by_email(credentials.email)
    if not user or not verify_password(credentials.password, user.password_hash):
        raise InvalidCredentialsError()
    return AuthResult(user=user, token=self.create_token(user))
\`\`\`

Quality Checklist

Before finalizing documentation, verify:

• Every major claim has a citation
• File paths are correct and exist
• Line numbers are current (if used)
• Code samples are copied from actual files (not invented)
• Citations use appropriate level for the claim's importance
• Cross-references to other documentation pages are valid

---

Version: 1.0 Last Updated: 2026-01-22