Technical Writing Standards

Apply these standards to ALL technical descriptions (systems, modules, components, APIs, interfaces).

Core Rules

Language Mechanics

• Active voice: "TireModel calculates forces" NOT "Forces are calculated"
• Present tense: "returns null" NOT "will return null"
• 15-20 words per sentence (max 30 before splitting)
• Code references: Use file_path:line_number format

Precision Requirements

Replace vague terms with specific measurements:

• "fast" → "completes in <100ms"
• "many" → "up to 1000 concurrent connections"
• "handles" → "validates/transforms/routes/stores" (specify which)
• "manages" → "creates/updates/deletes/tracks" (specify which)
• "processes" → "parses/filters/aggregates/formats" (specify which)
• "communicates" → "sends HTTP POST requests to"

Description Formats

System (1-2 sentences)

State WHAT the system does and WHY it exists using precise technical terminology.

Module/Component (2-3 sentences)

1. WHAT specific responsibility this owns
2. WHAT technical operations it performs
3. HOW it fits into larger architecture

Function/Method (structured)

Purpose: [1 sentence transformation/effect]
Parameters: [type, constraints, purpose]
Returns: [type, meaning, range/conditions]
Behavior: [2-4 sentences of observable behavior]
Errors: [what triggers them]

Relationship (2-5 words)

Be specific about what flows:

• ✅ "HTTP JSON requests", "Vehicle telemetry at 60Hz", "Validated credentials"
• ❌ "data", "information", "messages"

Quality Checklist

Before finalizing ANY description:

• Active voice throughout
• Present tense only
• No vague verbs without specifics
• Quantities have units/ranges
• Technical terms used precisely
• First use of acronyms spelled out
• Explains WHAT (technically) and WHY (purpose)

Examples

BAD: "The system handles user data and manages sessions."

GOOD: "The authentication service validates user credentials against PostgreSQL and issues JWT tokens with 24-hour expiration. It maintains session state in Redis with automatic cleanup after 30 minutes of inactivity."

BAD: "Component processes requests quickly."

GOOD: "RequestHandler parses incoming HTTP requests, validates JSON schema, and routes to appropriate controllers within 50ms p95 latency."

Anti-patterns

Never write:

• "This component handles various operations"
• "The module is responsible for managing things"
• "Processes data as needed"
• "Communicates with other services"
• "Main system functionality"

Always specify WHAT operations, WHICH things, WHAT data, HOW it communicates, WHAT functionality.

Never summarize content that already exists elsewhere:

• Skills will be loaded automatically. Don't explain what they contain.
• Files exist in the codebase. Don't repeat their contents.
• Documentation references point to source. Don't duplicate the information.
• If content exists, reference it. Don't summarize it.

Application

Use these standards for:

• Architecture descriptions
• API documentation
• Component specifications
• Interface contracts
• Technical decision records
• System documentation

When receiving vague input, ask:

• "What specific operations?"
• "What exact data types?"
• "Which protocol/format?"
• "What triggers this?"

Remember: Every word should add technical understanding. If it doesn't teach something specific about the system, cut it.