Skip to content

Repository Documentation Policy

🎯 Purpose

This policy ensures all user-facing documentation is properly organized in the docs/ structure for MkDocs integration and prevents broken links from scattered documentation files.

🏇 Business Model Self-Containment Principle

📜 Each Model = Complete Functional Unit

Business models represent MAJOR functionality additions and should be completely self-contained:

  • All model-related code (agents, FSM definitions, configuration)
  • All model-specific documentation (workflows, specifications, status)
  • All model setup data (templates, sample configurations)
  • All model tests (unit tests, scenario tests, integration tests)
  • Model-specific diagrams (state diagrams, interaction flows)

🔗 Cross-Reference Pattern

Models should reference platform architecture docs in docs/ for: - Shared design patterns and principles - Platform-wide architectural guidelines - Common development practices - Integration patterns with other system components

Example: models/bss/README.md links to docs/architecture/fsm-duality-framework.md for FSM implementation guidelines.

📋 Documentation Organization Rules

✅ REQUIRED: All Served Documentation in docs/

  • All user-facing documentation MUST be in docs/ structure
  • MkDocs navigation is built from docs/ content only
  • No documentation should exist outside docs/ that needs to be publicly accessible

🗂️ Standard Directory Structure

docs/
├── index.md                    # Homepage (replaces README.md in docs)
├── architecture/               # Platform architecture documentation
├── business/                   # Business model documentation
├── design/                     # Design specifications and guides
├── developer/                  # Quick start and developer overview
├── developer-guides/           # Detailed developer guides
├── diagrams/                   # Architectural diagrams and analysis
└── archived/                   # Legacy/deprecated documentation

models/                         # Business model implementations (SELF-CONTAINED)
├── bss/                        # Battery Swap Service (complete model)
│   ├── README.md               # Model overview and documentation
│   ├── model-status.md         # Implementation status
│   ├── bss-agent-v2.ts         # Agent implementation
│   ├── bss-fsm-v1.json         # FSM definitions
│   ├── design-intent/          # Business logic and workflows
│   ├── setup-data/             # Configuration files
│   ├── tests/                  # Model-specific tests
│   └── diagrams/               # Model-specific diagrams
└── [future-models]/            # Additional business models

🚫 PROHIBITED: Documentation Outside docs/

  • No markdown files for user documentation outside docs/
  • Ad-hoc documentation in root directory
  • Duplicate documentation in multiple locations
  • Development notes mixed with user documentation

📁 File Classification Guidelines

✅ Belongs in docs/ (Platform Documentation)

  • Platform architecture specifications
  • Cross-model design patterns
  • Developer guides and tutorials
  • Platform API documentation
  • System overviews
  • Infrastructure documentation
  • Platform-wide reference materials

✅ Belongs in models/ (Business Model Implementation)

  • Model-specific documentation (README.md, model-status.md)
  • Business logic specifications
  • Model implementation code
  • Model-specific workflows and design intent
  • Model configuration and setup data
  • Model-specific tests and diagrams
  • Model interaction patterns

🚫 Does NOT belong in docs/ (Keep in repo root or other locations)

  • README.md (repository overview - stays in root)
  • Setup/installation scripts
  • Deployment instructions for internal use
  • Development environment setup
  • Temporary communication files
  • Personal notes and drafts
  • Build/CI configuration documentation
  • Internal team processes

🔧 Implementation Guidelines

When Adding New Documentation

  1. Determine audience: Public users vs. internal developers
  2. Choose proper location: docs/ for public, appropriate directory for internal
  3. Follow naming conventions: Use descriptive, lowercase-with-hyphens names
  4. Update navigation: Add to mkdocs.yml nav structure if public-facing
  5. Cross-reference properly: Use relative links within docs/ structure

When Moving Existing Documentation

  1. Check for references: Search for links to the file before moving
  2. Update all cross-references: Fix broken links after moving
  3. Test build: Ensure MkDocs builds without warnings
  4. Remove duplicates: Delete redundant copies
  • Use relative paths within docs/ structure: ../architecture/overview.md
  • Test all links regularly with MkDocs build
  • No absolute paths to internal repository files
  • Update links when restructuring files

🛠️ Enforcement Tools

Automated Checks

  • MkDocs build process will fail on broken links
  • GitHub Actions can validate documentation structure
  • Link checkers can identify orphaned files

Manual Reviews

  • Regular audits of markdown files outside docs/
  • Review process for new documentation
  • Periodic cleanup of obsolete files

🧹 Cleanup Procedures

When Files Are Found Outside docs/

  1. Evaluate purpose: Is this user-facing documentation?
  2. If yes: Move to appropriate docs/ subdirectory
  3. If no: Delete if obsolete, or keep in appropriate location
  4. Update references: Fix any broken links
  5. Test build: Ensure documentation still builds correctly

Duplicate File Resolution

  1. Compare content: Identify the most current version
  2. Choose canonical location: Prefer docs/ version for user content
  3. Delete duplicates: Remove redundant copies
  4. Update links: Point all references to canonical location

📊 Quality Metrics

Success Indicators

  • ✅ MkDocs builds without link warnings
  • ✅ No documentation files outside appropriate locations
  • ✅ Clear navigation structure in published documentation
  • ✅ No duplicate content across multiple files

Regular Maintenance

  • Monthly review of files outside docs/
  • Quarterly cleanup of obsolete documentation
  • Immediate fix of any broken links reported by MkDocs
  • Team education on proper documentation placement

🚀 Migration Completed

Removed Files (2025-01-06)

The following ad-hoc files were removed during the initial consolidation: - _sidebar.md - Legacy navigation (not used by MkDocs) - mkdocs-setup.md - Setup instructions (internal documentation) - SHAREPOINT_*.md and TEAMS_*.md - Deployment guides (internal processes) - diagrams/ERD_SCHEMA_COMPARISON.md - Duplicate content (canonical version in docs/diagrams/)

Models Directory Restored (2025-01-06)

The models/ directory was initially moved to docs/models/ but has been restored to its original location following the business model self-containment principle: - models/bss/ - Complete Battery Swap Service implementation with all documentation, code, and configuration - MkDocs navigation updated to reference ../models/ for model documentation - Each business model remains a self-contained functional unit

Current State

  • ✅ Platform documentation centralized in docs/
  • ✅ Business models self-contained in models/
  • ✅ MkDocs builds without link warnings
  • ✅ Clean separation between platform and model documentation
  • ✅ Cross-references between platform docs and model implementations

📞 Contact

For questions about documentation organization or policy violations, please create an issue in the repository or contact the documentation maintainers.