Documentation Guidelines (CLAUDE.md)

This guide provides comprehensive information about the documentation system for the Comma project. It covers how to set up, write, test, and maintain the project's documentation.

Documentation Structure

The documentation follows a component-based approach aligned with the project's architecture:

docs/
├── .vuepress/        # VuePress configuration and themes
├── api/              # API documentation
│   ├── rest/         # REST API documentation
│   └── graphql/      # GraphQL API documentation
├── components/       # UI component documentation
├── infrastructure/   # Infrastructure documentation
├── ai/               # AI-related documentation
│   ├── architecture/ # AI system design
│   ├── prompts/      # AI prompt engineering
│   └── labs/         # Experimental AI features
├── guides/           # User and developer guides
│   ├── development/  # Development setup and workflow
│   ├── deployment/   # Deployment procedures
│   └── operations/   # Monitoring and maintenance
└── CLAUDE.md         # This documentation guide

Each section is designed to be self-contained while cross-referencing related content. The hierarchical structure helps users navigate through the documentation based on their specific needs.

VuePress Setup and Configuration

Environment Setup

  1. Prerequisites:

    • Node.js 16+ and npm
    • Basic knowledge of Markdown and Vue.js

  2. Local development setup:

    # Clone the repository
git clone https://github.com/your-org/comma.git
cd comma/docs

# Install dependencies
npm install

# Start the dev server
npm run dev

  3. Building for production:

    npm run build

Troubleshooting Common Issues

If you encounter errors when running the development server, try these steps:

  1. Missing dependencies:

    # Clean and reinstall dependencies
rm -rf node_modules package-lock.json
npm install

  2. Broken relative links:

    • Make sure to use the correct relative paths based on the file structure
    • For example, links from guides/deployment/ to infrastructure/ should use ../../infrastructure/ as the path prefix

Configuration Files

The VuePress configuration is maintained in .vuepress/config.js:

  • Site metadata: Title, description, base URL
  • Theme configuration: Navigation, sidebar, repo information
  • Plugins: Search, medium-zoom, etc.

When making changes to the configuration:

  1. Update the .vuepress/config.js file
  2. Test the changes locally using npm run dev
  3. Commit configuration changes with detailed explanations

Custom Components

Custom Vue components can be added in the .vuepress/components/ directory and will be automatically registered globally. Use them to create consistent, reusable documentation elements.

Technical Writing Style Guide

General Principles

  1. Clear and concise: Use simple, direct language
  2. Task-focused: Organize content around user tasks and goals
  3. Consistent terminology: Use the same terms consistently throughout
  4. Progressive disclosure: Present basic information first, with details later
  5. Scannable content: Use headings, lists, and formatting to aid scanning

Voice and Tone

  • Use active voice whenever possible
  • Address the reader directly ("you") rather than using passive voice
  • Maintain a professional but conversational tone
  • Be inclusive and respectful in all content

Formatting Standards

  • Use semantic heading levels (H1 for page title, H2 for major sections, etc.)
  • Limit paragraphs to 3-5 sentences
  • Use numbered lists for sequences and bulleted lists for unordered items
  • Highlight important notes, warnings, and tips using callouts:
::: tip
This is a helpful tip for users.
:::

::: warning
This is an important warning.
:::

::: danger
This indicates a dangerous or destructive action.
:::

API Documentation Best Practices

REST API Documentation

  1. Resource-oriented structure:

    • Group endpoints by resource type
    • Document resource models/schemas first, then operations

  2. Endpoint documentation template:

    ## Endpoint Name

`METHOD /path/to/endpoint`

Brief description of what this endpoint does.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| param1 | string | Yes | Description of parameter |

### Request Example

```http
# Example request with proper formatting

    Response Examples

    Success Response (200 OK)

    # Example response JSON

    Error Response (400 Bad Request)

    # Example error response

    Notes

    Additional information about usage, rate limits, etc.

  3. Authentication: Clearly document authentication requirements

  4. Error handling: Document common error codes and their meanings

  5. Rate limiting: Document any API rate limits and quotas

GraphQL API Documentation

  1. Schema-first approach: Document types, queries, and mutations
  2. Interactive examples: Use embedded GraphQL playground when possible
  3. Operation examples: Provide example queries and mutations

Code Examples and Snippets Formatting

Code Block Standards

Use fenced code blocks with language identifiers for syntax highlighting:

```python
def example_function():
    """Example function docstring."""
    return "Hello, World!"
```

Example Types

Include different types of examples:

  1. Context examples: Show where/when to use the code
  2. Basic examples: Simple demonstrations of core functionality
  3. Advanced examples: More complex use cases
  4. Error handling examples: How to handle exceptions and edge cases

Best Practices

  • Include comments in code examples
  • For longer examples, use line numbers
  • Ensure all examples are tested and functional
  • Link to complete example files in the repository when appropriate
  • Use consistent naming conventions across examples

Documentation Testing and Verification

Content Validation

  1. Technical accuracy:

    • Verify all commands and code examples work as documented
    • Cross-reference with the actual implementation
    • Update when APIs or features change

  2. Link validation:

    • Test internal and external links regularly
    • Fix broken links promptly

  3. Spelling and grammar:

    • Use automated tools to check spelling and grammar
    • Maintain a project-specific terminology glossary

User Testing

  1. Feedback methods:

    • Incorporate user feedback mechanisms on each page
    • Conduct periodic documentation reviews with new team members
    • Track common support questions that might indicate documentation gaps

  2. Metrics to track:

    • Page views and time spent on pages
    • Search terms used within the documentation
    • Documentation issue reports

Version Control for Documentation

Git Workflow

  1. Branch strategy:

    • Use feature branches for significant documentation changes
    • Create branches from main or the appropriate development branch
    • Follow the naming convention: docs/topic-name

  2. Commit guidelines:

    • Write clear commit messages explaining what changed and why
    • Group related documentation changes in a single commit
    • Reference related issues or tickets in commit messages

  3. Documentation versioning:

    • Tag documentation versions alongside code releases
    • Maintain separate branches for major version documentation when needed

Document Review Process

Review Workflow

  1. Pre-review checklist:

    • Run local build to verify formatting
    • Check links are working
    • Verify code examples run as expected
    • Ensure content follows style guidelines

  2. Review steps:

    • Submit documentation changes via pull request
    • Request reviews from subject matter experts
    • Address all comments and suggestions
    • Obtain final approval before merging

  3. Quality criteria:

    • Technical accuracy
    • Completeness
    • Clarity and readability
    • Adherence to style guide

Markdown Best Practices

Structure and Formatting

  1. File organization:

    • Use one Markdown file per major topic
    • Place files in appropriate directory based on content
    • Use lowercase, hyphenated filenames (e.g., api-authentication.md)

  2. Content structure:

    • Start with an H1 title
    • Use hierarchical headings (H2, H3, etc.) for subtopics
    • Add table of contents for longer documents

  3. Formatting guidelines:

    • Use backticks for inline code: `code`
    • Use triple backticks for code blocks with language identifier
    • Use bold (text) for emphasis and important terms
    • Use italics (text) for new terms and parameters
    • Use blockquotes (> text) for notes or quotes

Markdown Extensions

VuePress supports several Markdown extensions:

  1. Frontmatter: Add metadata at the top of files

    ---
title: Page Title
description: Page description for SEO
tags: [tag1, tag2]
---

  2. Custom containers: Use for tips, warnings, and notes

    ::: tip
This is a tip
:::

::: warning
This is a warning
:::

::: danger
This is a dangerous warning
:::

  3. Table of contents: Insert table of contents

    [[toc]]

  4. Emoji: Use emoji shortcodes

    :smile: :tada: :warning:

Search Optimization for Documentation

Content Optimization

  1. Page titles and headings:

    • Use descriptive, keyword-rich titles
    • Structure content with proper heading hierarchy
    • Include common terms users might search for

  2. Metadata:

    • Add description in frontmatter for each page
    • Include relevant tags for categorization

  3. Content quality:

    • Answer common questions clearly
    • Use terminology consistently
    • Include synonyms for technical terms

Technical Optimization

  1. Search index configuration:

    • Customize the search plugin in .vuepress/config.js
    • Configure search weights for different content types
    • Include code blocks in search when relevant

  2. Monitoring and improvement:

    • Review search analytics to identify common searches
    • Add content addressing frequently searched topics
    • Adjust terminology based on search patterns

Documentation Maintenance

Regular Updates

  1. Scheduled reviews:

    • Review each section quarterly
    • Update for new features after each release
    • Perform full audit annually

  2. Deprecation process:

    • Clearly mark deprecated features
    • Provide migration guidance
    • Maintain archives of historical documentation when needed

Feedback Loop

  1. Collecting feedback:

    • Add feedback mechanisms on documentation pages
    • Monitor support channels for documentation-related questions
    • Check analytics for poorly performing pages

  2. Implementation process:

    • Prioritize feedback based on impact and user needs
    • Schedule regular documentation sprints
    • Assign documentation tasks to subject matter experts

Contributing to Documentation

We welcome contributions to improve our documentation! Here's how you can help:

  1. Report issues: Found an error or unclear explanation? Open an issue.
  2. Suggest improvements: Have ideas for better documentation? Share them.
  3. Submit changes: Make a pull request with your proposed changes.

For substantial contributions, please follow the full documentation process outlined in this guide.

This CLAUDE.md guide serves as a living document. Update it as documentation processes evolve.