Content & Documentation Generator

Purpose & When-To-Use

Trigger conditions:

• New feature requires documentation
• API endpoint needs OpenAPI-driven documentation
• User guide or tutorial creation needed
• Documentation refresh for clarity and accessibility
• Knowledge base article generation
• Migration from wiki/docs to structured documentation site

Not for:

• Marketing copy or sales materials
• Legal documents or contracts
• Research papers or academic writing
• Long-form narrative content

Pre-Checks

Time normalization:

• Compute NOW_ET using NIST/time.gov semantics (America/New_York, ISO-8601)
• Use NOW_ET for all citation access dates

Input validation:

• content_type must be one of: technical-doc, api-doc, user-guide, tutorial
• source must be valid (file exists, spec parseable, or non-empty string)
• output_format must be: markdown, mdx, or html
• style_guide must be: microsoft, google, or write-the-docs

Source freshness:

• For API docs: verify OpenAPI spec version (3.0.x or 3.1.x supported)
• Style guide references accessible and current

Procedure

T1: Standard Documentation Generation (≤2k tokens)

Fast path for 80% of documentation needs:

1. Content Analysis

   • Detect content type from source or use provided content_type
   • Identify key sections needed (overview, quickstart, reference, examples)

2. Template Selection (Write the Docs Structure Guide, accessed 2025-10-25T21:30:36-04:00)

   • Technical Doc: Title, Purpose, Prerequisites, Steps, Troubleshooting, Next Steps
   • API Doc: Endpoint description, Request/Response schemas, Examples, Error codes
   • User Guide: Introduction, Task-based sections, Screenshots/diagrams, FAQs
   • Tutorial: Learning objectives, Step-by-step instructions, Code samples, Validation

3. Content Generation Principles (Google Technical Writing Guide, accessed 2025-10-25T21:30:36-04:00)

   • Use active voice and present tense
   • Keep sentences ≤25 words
   • Use concrete examples over abstract concepts
   • Front-load important information
   • Use bulleted lists for 3+ items
   • Add code blocks with language identifiers

4. Accessibility Checks (WCAG 2.2 Level AA, accessed 2025-10-25T21:30:36-04:00)

   • Headings in logical hierarchy (H1 → H2 → H3)
   • Descriptive link text (no "click here")
   • Alt text for images
   • Color contrast sufficient (4.5:1 for text)
   • No flashing content

5. Metadata Generation

   • Generate frontmatter: title, description (≤160 chars), keywords, date
   • Create navigation breadcrumbs if part of doc site

Output: Markdown/MDX document with frontmatter and accessibility-compliant structure.

Decision: If content_type == "api-doc" and OpenAPI spec provided → proceed to T2 for enhanced API documentation. Otherwise STOP at T1.

T2: API Documentation Enhancement (≤6k tokens)

Extended API documentation from OpenAPI specifications:

1. OpenAPI Parsing

   • Parse OpenAPI 3.0.x or 3.1.x specification
   • Extract endpoints, schemas, security schemes
   • Validate spec completeness (descriptions, examples present)

2. Enhanced Documentation Sections (Docusaurus OpenAPI Docs, accessed 2025-10-25T21:30:36-04:00)

   • Overview: API purpose, base URL, authentication methods
   • Authentication: Security scheme details with examples
   • Endpoints by Resource: Group by tags, show HTTP methods
   • Request Details: Parameters (path/query/header/body), schemas, constraints
   • Response Details: Status codes, response schemas, examples
   • Error Handling: Common error codes and resolution steps
   • Rate Limiting: If defined in spec

3. Code Sample Generation

   • Generate request examples in 2-3 languages (curl, JavaScript, Python)
   • Include authentication headers
   • Use realistic sample data from OpenAPI examples

4. Interactive Features (for MDX output)

   • Try-it-out component metadata
   • Collapsible schema sections
   • Tabbed code examples

Output: Comprehensive API documentation with code samples and interactive elements.

T3: Documentation Site Generation (not implemented in v1.0.0)

Reserved for:

• Full documentation site scaffolding (Docusaurus/MkDocs)
• Multi-version documentation management
• Search indexing and algolia integration
• Documentation analytics and feedback collection

Decision Rules

Content Type Detection:

• If source contains openapi or swagger key → api-doc
• If source is directory with code files → technical-doc
• If source is plain text brief → user-guide or tutorial (ask user if ambiguous)

Abort Conditions:

• OpenAPI spec invalid or unparseable → error "Invalid OpenAPI specification"
• Source file not found → error "Source file not accessible"
• Unsupported OpenAPI version → error "Only OpenAPI 3.0.x and 3.1.x supported"

Accessibility Threshold:

• Score ≥90 → "Excellent accessibility"
• Score 70-89 → "Good accessibility, minor improvements suggested"
• Score <70 → Include remediation recommendations in output

Style Guide Conflicts:

• When style guides conflict, prefer: write-the-docs > google > microsoft
• Document style guide choice in frontmatter

Output Contract

Required fields:

documentation:
  type: string
  description: "Generated documentation content in requested format"
  format: "markdown | mdx | html"

metadata:
  type: object
  required: [title, description, keywords, generated_at]
  properties:
    title:
      type: string
      maxLength: 60
    description:
      type: string
      maxLength: 160
    keywords:
      type: array
      items: {type: string}
      maxItems: 10
    generated_at:
      type: string
      format: date-time
    style_guide:
      type: string
      enum: [microsoft, google, write-the-docs]

accessibility_score:
  type: integer
  minimum: 0
  maximum: 100
  description: "WCAG 2.2 Level AA compliance rating"

issues:
  type: array
  description: "Accessibility or style issues found (optional)"
  items:
    type: object
    properties:
      severity: {type: string, enum: [error, warning, info]}
      message: {type: string}
      line: {type: integer}

Examples

Input:

content_type: "api-doc"
source: "openapi-spec.yaml"
output_format: "markdown"
style_guide: "write-the-docs"

Output (abbreviated):

---
title: "User Management API"
description: "REST API for user authentication and profile management"
keywords: [api, users, authentication, rest]
generated_at: "2025-10-25T21:30:36-04:00"
style_guide: "write-the-docs"
---

# User Management API

Manage user accounts and authentication.

## Authentication
Bearer token required. Include in `Authorization` header.

## Endpoints

### POST /users/register
Create new user account.

**Request:**
```json
{"email": "user@example.com", "password": "***"}

Response (201):

{"id": "usr_123", "email": "user@example.com"}

---

## Quality Gates

**Token budgets (mandatory):**
- **T1 ≤ 2k tokens** — Standard doc generation (technical-doc, user-guide, tutorial)
- **T2 ≤ 6k tokens** — API documentation with OpenAPI parsing and code samples
- **T3 ≤ 12k tokens** — (Not implemented) Full site generation

**Safety:**
- No secrets in documentation examples
- Sanitize user-provided content
- No executable code in examples (documentation only)

**Auditability:**
- All style guide references cite specific sections with access dates
- Template choices logged in metadata
- Accessibility issues enumerated with severity

**Determinism:**
- Same input + style guide → same output structure
- Variation acceptable in generated examples (realistic data)

---

## Resources

**Style Guides:**
- [Write the Docs Guide](https://www.writethedocs.org/guide/) — Community best practices
- [Google Technical Writing Courses](https://developers.google.com/tech-writing) — Free courses on clarity
- [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) — Enterprise style guide

**Documentation Tools:**
- [Docusaurus](https://docusaurus.io/docs) — React-based doc site generator
- [MkDocs](https://www.mkdocs.org/) — Python-based static site generator
- [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) — Material Design theme for MkDocs

**Accessibility:**
- [WCAG 2.2 Quick Reference](https://www.w3.org/WAI/WCAG22/quickref/) — Official guidelines
- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) — Color contrast validation

**OpenAPI:**
- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html) — Official spec
- [Swagger Editor](https://editor.swagger.io/) — Online OpenAPI editor

**Templates:**
- See `resources/templates/` for reusable Markdown templates
- See `resources/schemas/` for JSON schemas