Tech Specs Writer

Target Directories

• docs/reference/ - General reference (API, CLI, config)
• docs/reference/api/ - API documentation
• docs/technical/ - Technical specifications, data models

Writing Guidelines

DO

• Be factual and descriptive
• Structure consistently (tables, lists)
• Prioritize completeness and accuracy
• Match the structure of what you're documenting
• Use consistent formatting throughout
• Include all parameters, options, return values
• Provide type information

DON'T

• Mix in tutorials or how-tos
• Explain concepts (link to explanations)
• Include opinions or recommendations
• Skip edge cases or error states
• Assume context (be explicit)

Architecture-Agnostic Principles

Reference docs should work regardless of implementation. Focus on:

Test: "Could a developer use this to build a CLI that does the same thing?"

Examples of Good Reference Docs

• "API Endpoints Reference"
• "Configuration Options"
• "CLI Commands"
• "Data Models"
• "Error Codes"

Template

Use this template when creating technical specification documentation:

# [Feature/Component] Specification

*Last updated: [YYYY-MM-DD]*
*Version: [X.Y.Z]*

## Overview

[1-2 sentences describing what this document specifies]

## Requirements

### Functional Requirements

| ID | Requirement | Priority |
|----|-------------|----------|
| FR-1 | [Requirement description] | [Must/Should/Could] |
| FR-2 | [Requirement description] | [Must/Should/Could] |

### Non-Functional Requirements

| ID | Requirement | Metric |
|----|-------------|--------|
| NFR-1 | [Performance/Security/etc.] | [Measurable target] |

## Data Model

### [Entity Name]

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | string | Yes | Unique identifier |
| [field] | [type] | [Yes/No] | [Description] |
| [field] | [type] | [Yes/No] | [Description] |

### Relationships

[Entity A] 1──────* [Entity B]
     │
     └──────1 [Entity C]

## API Contract

### [Endpoint/Method Name]

**Endpoint:** `[METHOD] /path/to/resource`

**Request:**

{
  "[field]": "[type] - [description]"
}

**Response:**

{
  "[field]": "[type] - [description]"
}

**Errors:**

| Status | Code | Description |
|--------|------|-------------|
| 400 | INVALID_INPUT | [When this occurs] |
| 404 | NOT_FOUND | [When this occurs] |

## Validation Rules

| Field | Rule | Error Message |
|-------|------|---------------|
| [field] | [validation rule] | [user-facing message] |

## Constraints

- [Constraint 1 - e.g., Maximum 100 items per request]
- [Constraint 2 - e.g., Field X must be unique per user]

## Dependencies

| Dependency | Type | Purpose |
|------------|------|---------|
| [Service/Component] | [Internal/External] | [Why needed] |

## Security Considerations

- [Security requirement 1]
- [Security requirement 2]

## Related Documents

- [Architecture Decision Record](../architecture/ADR-XXX.md)
- [API Reference](../reference/api/ENDPOINT.md)

Quality Checklist

Apply this checklist before finalizing any reference documentation.

Completeness

• All parameters/options are documented
• All return values/responses are documented
• All error codes/states are documented
• All edge cases are covered
• No TODO or TBD sections remain

Accuracy

• Information matches current implementation
• Code examples have been tested
• Type information is correct
• Default values are accurate
• Constraints are verified

Structure

• Consistent format throughout
• Tables used for structured data
• Matches the structure of what's documented
• Logical organization

Architecture-Agnostic

• Documents data requirements, not UI
• Documents API contracts, not framework code
• Could be used to build a CLI equivalent
• No implementation-specific details

Clarity

• Descriptions are factual and precise
• No ambiguous language
• Technical terms are consistent
• Required vs optional is clear

Neutrality

• No opinions or recommendations
• No tutorial-style instructions
• No how-to content mixed in
• Tone is austere and professional

Maintainability

• Single source of truth (no duplicates)
• Version/date stamp if time-sensitive
• Cross-references use relative links
• Easy to update when API changes

Formatting

• Consistent table structure
• Code blocks have language specified
• Proper use of inline code for values
• No broken links