@noanswer/context-compose/assets/rules/documentation-standards.yaml

Orchestrate complex AI interactions with Context Compose. A powerful CLI and server for building, validating, and managing context for large language models using the Model Context Protocol (MCP).

version: 1
kind: rule
name: Documentation Standards
description: Comprehensive documentation standards for maintainable and accessible code
prompt: |
  Write clear and consistent code and API documentation using JSDoc, OpenAPI, etc.
  Include features, quick start, installation, usage, and contribution guides in the README.
  Keep all documentation synchronized with code changes and include practical examples.
  Record architectural decisions in ADRs (Architecture Decision Records) for sharing.
enhanced-prompt: |-
  ### Documentation Philosophy
  - **User-Centric Approach**: Write for your audience (developers, users), explaining the "why," not just the "what." Include practical examples and use cases to aid understanding.
  - **Living Documentation**: Keep documentation consistently up-to-date with code changes. Integrate documentation into the development workflow and conduct regular reviews.

  ### Code & API Documentation
  - **JSDoc/TSDoc**: Write JSDoc comments for all public functions, methods, and classes. Clearly describe parameters (`@param`), return values (`@returns`), exceptions (`@throws`), and provide examples (`@example`).
  - **API Specification**: For REST APIs, use the OpenAPI (Swagger) specification to define endpoints, parameters, responses, and authentication requirements. For GraphQL APIs, include descriptions within the schema.

  ### Project Documentation
  - **README.md**: This is the main entry point for the project. Follow this structure:
      - **Introduction**: Briefly explain the project's purpose and features.
      - **Quick Start**: Guide users to run the project with a few commands.
      - **Installation**: Detail prerequisites and step-by-step installation.
      - **Usage**: Provide basic and advanced usage examples.
      - **API**: (If necessary) Provide a brief reference for the public API.
      - **Contributing**: Link to `CONTRIBUTING.md` and explain the process.
      - **License**: Specify the project's license.
  - **CONTRIBUTING.md**: Detail how to contribute, including code style, commit message conventions, and the PR process.
  - **CHANGELOG.md**: Document changes for each version, categorized into sections like "Added," "Changed," "Fixed," and "Removed," so users can easily track them.

  ### Architecture Documentation
  - **Architecture Decision Records (ADRs)**: Record significant architectural decisions (e.g., tech stack choices, key patterns) using ADRs. Include the 'Context,' 'Decision,' and 'Consequences' to track the reasoning over time.