Contributing to Atlas Documentation

This section provides comprehensive guidelines for contributing to the Atlas project documentation. Our documentation follows the structure of the Trimodal Methodology Framework, combining top-down design, bottom-up implementation, and holistic system integration perspectives.

Core Documentation Principles

1. Clarity and Precision: Use clear, concise language appropriate to the context. Provide specific examples for abstract concepts and define specialized terminology.

2. Adaptive Perspective: Present information from multiple perspectives (user, developer, designer) to accommodate different knowledge levels and usage patterns.

3. Progressive Disclosure: Start with essential concepts before diving into complexities. Layer information so readers can explore details as needed.

4. Consistency: Maintain consistent terminology, formatting, and structure across all documentation.

5. Example-Driven: Provide concrete, runnable examples for all major features and concepts.

Documentation Structure

Our documentation is organized into these main sections:

1. Architecture: The system architecture is now documented in:

   • Architectural Patterns: Core architectural patterns (Top-Down)
   • Components: Core component implementation (Bottom-Up)
   • Composites: System integration components (Holistic)

2. Implementation: Implementation details are found in:

   • Implementation Guide: Implementation approach
   • Integration Guide: System integration
   • Type System: Type definitions

3. Project Management: Project planning and tracking:

   • Product Roadmap: Development roadmap
   • Implementation Plan: Execution plan
   • Progress Tracking: Implementation status

4. Reference: Reference documentation:

   • Licensing: Licensing information

Contribution Guides

These consolidated guides provide comprehensive standards and best practices for Atlas documentation:

Code Standards

Complete guide to code quality, formatting, and type system usage including:

• Code Examples: Standards for creating clear, instructive code examples
• Colored Diffs: Using visual diffs to highlight code changes
• Type System: Comprehensive type system guidelines and best practices
• Type Mappings: Handling type conversions between different systems

Documentation Guide

Comprehensive guide to writing high-quality documentation including:

• Writing Standards: Voice, tone, and style guidelines
• Content Containers: Using VitePress custom containers effectively
• Timeline Components: Creating chronological visualizations
• Visual Elements: Formatting, images, and accessibility

Implementation Guide

Technical setup and implementation patterns including:

• Development Environment: Setting up and using the development environment
• Schema Validation: Using Marshmallow for runtime validation
• Implementation Patterns: Common patterns for providers, agents, and tools

Getting Started

New contributors should start with the Implementation Guide to set up their development environment, then refer to the Code Standards for coding guidelines and the Documentation Guide for writing documentation.

Contribution Process

1. Plan: Determine where your content fits in the documentation structure
2. Setup: Follow the Implementation Guide to set up your development environment
3. Draft: Create your content following the appropriate guidelines
4. Review: Ensure content meets our standards for quality and clarity
5. Submit: Create a pull request with your changes
6. Iterate: Address feedback and refine your contribution

Key Guidelines Summary

For Code Contributions

• Follow the type system guidelines in Code Standards
• Use proper schema validation as outlined in Implementation Guide
• Include comprehensive examples following Code Standards
• Run all quality checks: uv run pytest, uv run mypy atlas, uv run ruff check .

For Documentation Contributions

• Follow the writing style in Documentation Guide
• Use custom containers appropriately (limit to 2-3 per page)
• Include practical code examples following Code Standards
• Test all links and code examples before submission

For Visual Elements

• Use timeline components sparingly for chronological processes
• Apply colored diffs to highlight important code changes
• Follow accessibility guidelines for images and diagrams
• Maintain visual consistency across documentation

Getting Help

If you’re unsure about how to contribute or have questions about documentation standards, please create an issue with the “documentation” label.

Quality Focus

Atlas prioritizes high-quality, consistent documentation that serves both newcomers and experienced developers. All contributions should enhance clarity, maintain consistency, and provide practical value to users.