project-standalo-sonic-cloud/skills/documentation-generator/schemas/documentation_output.yml

# Documentation Output Schema
# Defines the structure for generated documentation

version: "1.0"
description: Schema for dual-audience project documentation

output_files:
  main_documentation:
    filename: PROJECT_DOCUMENTATION.md
    required: true
    sections:
      - executive_summary
      - quick_start
      - architecture_overview
      - features
      - for_developers
      - glossary

  quick_reference:
    filename: QUICK_REFERENCE.md
    required: true
    sections:
      - commands
      - key_files
      - api_endpoints
      - environment_variables

  api_reference:
    filename: API_REFERENCE.md
    required: false
    condition: has_api_endpoints
    sections:
      - authentication
      - endpoints_by_resource
      - error_codes
      - rate_limiting

  components:
    filename: COMPONENTS.md
    required: false
    condition: has_ui_components
    sections:
      - component_index
      - component_details
      - usage_examples

section_schemas:
  executive_summary:
    description: High-level project overview for all audiences
    fields:
      project_name:
        type: string
        required: true
      tagline:
        type: string
        required: true
        max_length: 100
        description: One-line description in plain English
      what_it_does:
        type: string
        required: true
        description: 2-3 sentences, no technical jargon
      who_its_for:
        type: string
        required: true
        description: Target audience in plain English
      key_capabilities:
        type: array
        items:
          capability: string
          description: string
        min_items: 3
        max_items: 8

  quick_start:
    description: Getting started guide for new users
    fields:
      prerequisites:
        type: array
        items:
          tool: string
          purpose: string  # Plain English explanation
          install_command: string
      installation_steps:
        type: array
        items:
          step: integer
          command: string
          explanation: string  # What this does
      basic_usage:
        type: string
        description: Simple example of how to use

  architecture_overview:
    description: Visual system architecture
    fields:
      system_diagram:
        type: string
        format: ascii_art
        required: true
      technology_stack:
        type: array
        items:
          layer: string
          technology: string
          purpose: string  # Plain English
      directory_structure:
        type: string
        format: tree
        required: true

  features:
    description: Feature documentation for all audiences
    fields:
      features:
        type: array
        items:
          name: string
          what_it_does: string  # Plain English
          how_to_use: string    # Simple instructions
          example: string       # Code or usage example
          technical_notes: string  # For engineers, optional

  api_endpoint:
    description: Single API endpoint documentation
    fields:
      method:
        type: enum
        values: [GET, POST, PUT, PATCH, DELETE]
      path:
        type: string
        pattern: "^/api/"
      summary:
        type: string
        description: Plain English description
      description:
        type: string
        description: Detailed explanation
      authentication:
        type: object
        fields:
          required: boolean
          type: string  # bearer, api_key, session
      request:
        type: object
        fields:
          content_type: string
          body_schema: object
          query_params: array
          path_params: array
      responses:
        type: array
        items:
          status: integer
          description: string
          schema: object
      examples:
        type: array
        items:
          name: string
          request: object
          response: object

  component:
    description: UI component documentation
    fields:
      name:
        type: string
        pattern: "^[A-Z][a-zA-Z]*$"  # PascalCase
      path:
        type: string
      description:
        type: string
        description: Plain English purpose
      props:
        type: array
        items:
          name: string
          type: string
          required: boolean
          default: any
          description: string
      events:
        type: array
        items:
          name: string
          payload: string
          description: string
      usage_example:
        type: string
        format: code
      dependencies:
        type: array
        items: string

  data_model:
    description: Data model documentation
    fields:
      name:
        type: string
      description:
        type: string
        description: What data it represents (plain English)
      table_name:
        type: string
      fields:
        type: array
        items:
          name: string
          type: string
          description: string  # Plain English
          constraints: array
      relations:
        type: array
        items:
          type: enum
          values: [has_one, has_many, belongs_to, many_to_many]
          target: string
          description: string

  glossary_term:
    description: Technical term definition
    fields:
      term:
        type: string
        required: true
      definition:
        type: string
        required: true
        description: Plain English definition
      see_also:
        type: array
        items: string
        description: Related terms

audience_markers:
  non_technical:
    indicator: "📖"
    description: "For all readers"
  technical:
    indicator: "🔧"
    description: "For developers"
    wrapper: "<details><summary>🔧 Technical Details</summary>...content...</details>"

formatting_rules:
  headings:
    h1: "# Title"
    h2: "## Section"
    h3: "### Subsection"
  code_blocks:
    language_hints: required
    max_lines: 30
  tables:
    alignment: left
    max_columns: 5
  diagrams:
    format: ascii_art
    max_width: 80
  links:
    internal: "[text](#anchor)"
    external: "[text](url)"
    file_reference: "`path/to/file`"

validation_rules:
  - name: no_broken_links
    description: All internal links must resolve
  - name: code_syntax
    description: All code blocks must be syntactically valid
  - name: file_references
    description: All referenced files must exist
  - name: glossary_coverage
    description: All technical terms must be in glossary
  - name: diagram_rendering
    description: ASCII diagrams must render correctly