Content & Documentation Generator

name: "Content & Documentation Generator"
slug: "documentation-content-generator"
description: "Generate technical documentation, API docs, and content with accessibility and SEO optimization."
capabilities:
- Generate Markdown/MDX documentation from templates
- Create API documentation from OpenAPI specifications
- Apply technical writing best practices (clarity, structure, readability)
- Optimize for accessibility (WCAG 2.2 compliance)
- Generate documentation site structures
inputs:
- content_type: "technical-doc | api-doc | user-guide | tutorial (string)"
- source: "code path, OpenAPI spec, or content brief (string)"
- output_format: "markdown | mdx | html (string, default: markdown)"
- style_guide: "microsoft | google | write-the-docs (string, default: write-the-docs)"
outputs:
- documentation: "Generated documentation in specified format (string)"
- metadata: "SEO metadata and frontmatter (object)"
- accessibility_score: "WCAG compliance rating 0-100 (integer)"
keywords:
- documentation
- technical-writing
- api-docs
- markdown
- accessibility
- content-generation
version: "1.0.0"
owner: "cognitive-toolworks"
license: "MIT"
security: "Public; no secrets or PII; safe for open repositories"
links:
- https://www.writethedocs.org/guide/
- https://docusaurus.io/docs
- https://www.mkdocs.org/
- https://developers.google.com/tech-writing
- https://www.w3.org/WAI/WCAG22/quickref/

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
2. Detect content type from source or use provided content_type

3. Identify key sections needed (overview, quickstart, reference, examples)

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

5. Technical Doc: Title, Purpose, Prerequisites, Steps, Troubleshooting, Next Steps
6. API Doc: Endpoint description, Request/Response schemas, Examples, Error codes
7. User Guide: Introduction, Task-based sections, Screenshots/diagrams, FAQs

8. Tutorial: Learning objectives, Step-by-step instructions, Code samples, Validation

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

10. Use active voice and present tense
11. Keep sentences ≤25 words
12. Use concrete examples over abstract concepts
13. Front-load important information
14. Use bulleted lists for 3+ items

15. Add code blocks with language identifiers

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

17. Headings in logical hierarchy (H1 → H2 → H3)
18. Descriptive link text (no "click here")
19. Alt text for images
20. Color contrast sufficient (4.5:1 for text)

21. No flashing content

22. Metadata Generation

23. Generate frontmatter: title, description (≤160 chars), keywords, date
24. 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
2. Parse OpenAPI 3.0.x or 3.1.x specification
3. Extract endpoints, schemas, security schemes

4. Validate spec completeness (descriptions, examples present)

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

6. Overview: API purpose, base URL, authentication methods
7. Authentication: Security scheme details with examples
8. Endpoints by Resource: Group by tags, show HTTP methods
9. Request Details: Parameters (path/query/header/body), schemas, constraints
10. Response Details: Status codes, response schemas, examples
11. Error Handling: Common error codes and resolution steps

12. Rate Limiting: If defined in spec

13. Code Sample Generation

14. Generate request examples in 2-3 languages (curl, JavaScript, Python)
15. Include authentication headers

16. Use realistic sample data from OpenAPI examples

17. Interactive Features (for MDX output)

18. Try-it-out component metadata
19. Collapsible schema sections
20. 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": "[email protected]", "password": "***"}

Response (201):

{"id": "usr_123", "email": "[email protected]"}

```

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