williamzujkowski/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)

1. 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

1. 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

1. 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

1. 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)

1. 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

1. Code Sample Generation

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

1. 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:

yaml
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:

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

Output (abbreviated):

markdown
---
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:**

{"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 — Community best practices
• Google Technical Writing Courses — Free courses on clarity
• Microsoft Writing Style Guide — Enterprise style guide

Documentation Tools:

• Docusaurus — React-based doc site generator
• MkDocs — Python-based static site generator
• MkDocs Material — Material Design theme for MkDocs

Accessibility:

• WCAG 2.2 Quick Reference — Official guidelines
• WebAIM Contrast Checker — Color contrast validation

OpenAPI:

• OpenAPI Specification — Official spec
• Swagger Editor — Online OpenAPI editor

Templates:

• See resources/templates/ for reusable Markdown templates
• See resources/schemas/ for JSON schemas