Skip to content
This repository was archived by the owner on May 27, 2026. It is now read-only.

STRUCTURE.md

Latest commit

 

History

History
193 lines (162 loc) · 8.41 KB

STRUCTURE.md

File metadata and controls

193 lines (162 loc) · 8.41 KB
Raw

GitFlow Analytics Documentation Structure

This document describes the organization and structure of GitFlow Analytics documentation, designed to serve different audiences with clear navigation paths.

📚 Documentation Philosophy

Our documentation follows a progressive disclosure model:

  • Users find what they need to get started quickly
  • Developers can dive deep into implementation details
  • Contributors have clear guidance on project standards
  • Maintainers have architectural context for decisions

🏗️ Directory Structure

docs/
├── README.md                    # Documentation index and navigation
├── STRUCTURE.md                 # This file - documentation organization guide
├── getting-started/            # User onboarding and quick wins
│   ├── README.md               # Getting started index
│   ├── installation.md         # Installation and setup
│   ├── quickstart.md          # 5-minute tutorial
│   └── first-analysis.md      # Your first repository analysis
├── guides/                     # Task-oriented user guides
│   ├── README.md              # Guides index
│   ├── chatgpt-setup.md       # LLM integration setup
│   ├── ml-categorization.md   # ML features setup and usage
│   ├── troubleshooting.md     # Common issues and solutions
│   └── LLM_CLASSIFICATION_GUIDE.md # LLM classification guide
├── examples/                   # Real-world usage examples
│   ├── README.md              # Examples index
│   ├── basic-analysis.md      # Simple single-repo analysis
│   ├── enterprise-setup.md    # Large organization configuration
│   ├── ci-integration.md      # Continuous integration examples
│   └── custom-workflows.md    # Advanced workflow examples
├── reference/                  # Technical reference material
│   ├── README.md              # Reference index
│   ├── cli-commands.md        # Complete CLI reference
│   ├── configuration-schema.md # YAML configuration specification
│   ├── json-export-schema.md  # JSON export format documentation
│   └── cache-system.md        # Caching implementation details
├── developer/                  # Developer and contributor documentation
│   ├── README.md              # Developer documentation index
│   ├── contributing.md        # Contribution guidelines
│   ├── development-setup.md   # Local development environment
│   └── training-guide.md      # ML training guide
├── architecture/              # System design and architecture
│   ├── README.md              # Architecture documentation index
│   ├── branch-analysis-optimization.md # Branch analysis strategies
│   ├── ml-pipeline.md        # Machine learning architecture
│   ├── caching-strategy.md   # Incremental processing
│   └── llm-classifier-refactoring.md # LLM classifier architecture
├── design/                    # Design documents and decisions
│   ├── README.md              # Design documents index
│   ├── commit-classification-design.md # ML classification system design
│   ├── git_pm_correlation_design.md # Git-PM correlation design
│   ├── platform-agnostic-pm-framework.md # PM framework design
│   └── qualitative_data_extraction.md # Qualitative analysis design
├── configuration/             # Configuration documentation
│   └── configuration.md      # Comprehensive configuration guide
└── deployment/                # Operations and deployment
    └── README.md              # Deployment documentation index
    ├── installation.md        # Production deployment guide
    ├── monitoring.md          # Performance monitoring and metrics
    ├── security.md           # Security considerations and best practices
    └── scaling.md            # Scaling for large organizations

🎯 Audience-Specific Navigation

For New Users

Start here: docs/getting-started/ → docs/examples/basic-analysis.md

  1. Installation Guide
  2. Quick Start Tutorial
  3. Your First Analysis
  4. Basic Analysis Example

For Power Users

Start here: docs/guides/ → docs/examples/enterprise-setup.md

  1. Complete Configuration Guide
  2. ML Categorization Setup
  3. Organization-Wide Analysis
  4. Enterprise Setup Example

For Developers

Start here: docs/developer/ → docs/architecture/

  1. Contributing Guidelines
  2. Development Setup
  3. System Architecture
  4. Coding Standards

For System Integrators

Start here: docs/reference/ → docs/deployment/

  1. CLI Command Reference
  2. JSON Export Schema
  3. Production Deployment
  4. CI Integration Examples

📋 Documentation Standards

File Naming Conventions

  • Use lowercase with hyphens: file-name.md
  • Be descriptive but concise: ml-categorization.md not ml.md
  • Use consistent suffixes: -guide.md, -reference.md, -overview.md

Content Structure

  1. Title and Brief Description - What this document covers
  2. Prerequisites - What users should know/have done first
  3. Step-by-Step Instructions - Clear, numbered procedures
  4. Examples - Real-world usage scenarios
  5. Troubleshooting - Common issues and solutions
  6. Next Steps - Where to go next

Cross-Referencing

  • Use relative links within documentation: [Configuration Guide](../guides/configuration.md)
  • Link to external resources with full URLs
  • Include "See Also" sections for related topics
  • Reference CLI commands with code blocks

Code Examples

  • Always provide complete, runnable examples
  • Include expected output when helpful
  • Use consistent formatting and style
  • Test all examples before committing

🔗 Integration Points

With Main README.md

The main project README.md provides overview and quick start, then directs users to:

  • docs/getting-started/ for detailed setup
  • docs/examples/ for usage scenarios
  • docs/guides/ for advanced configuration

With CLAUDE.md (Developer Instructions)

CLAUDE.md serves as the developer's companion to this documentation:

  • Links to docs/developer/ for contribution processes
  • References docs/architecture/ for system understanding
  • Points to docs/design/ for decision context

With Examples Directory

The root /examples/ directory contains:

  • Configuration files and scripts
  • Sample data and test cases
  • Integration examples

Documentation in docs/examples/ explains how to use these files.

🚀 Maintenance Guidelines

Regular Updates

  • Review and update documentation with each release
  • Validate all examples and code samples
  • Update screenshots and CLI output examples
  • Check for broken internal and external links

Content Ownership

  • User Documentation: Product owners and user experience
  • Developer Documentation: Core maintainers and contributors
  • Architecture Documentation: Technical leads and architects
  • Deployment Documentation: Operations and DevOps teams

Quality Checks

  • Use consistent voice and tone throughout
  • Ensure technical accuracy with SME reviews
  • Test all procedures and examples
  • Maintain accessibility standards

📈 Success Metrics

User Experience

  • Reduced time-to-first-success for new users
  • Decreased support requests for documented topics
  • Positive feedback on documentation clarity
  • High task completion rates in user testing

Developer Experience

  • Faster onboarding for new contributors
  • Consistent code quality and standards adherence
  • Reduced review cycles due to clear guidelines
  • Active community participation

Content Quality

  • Regular content audits and updates
  • Broken link monitoring and fixing
  • User feedback integration
  • Continuous improvement based on analytics

Documentation Maintainers: Update this structure document when adding new sections or changing organization.

Last Updated: January 2025
Version: 1.0