Bluefly Documentation Strategy

This guide outlines our documentation approach for the Bluefly LLM ecosystem, detailing how we structure, maintain, and improve our documentation.

Documentation Philosophy

Our documentation strategy follows these core principles:

1. Documentation as Code: Documentation lives alongside code, follows the same review process, and is versioned with Git.
2. Single Source of Truth: Information should exist in one place only to prevent inconsistencies.
3. Hybrid Approach: Project-specific documentation lives in project repositories, while comprehensive system-wide documentation lives in this central repository (BFDOCS).
4. Audience-Oriented: Documentation is organized based on user roles and needs, not just system architecture.
5. Continuous Improvement: Documentation evolves alongside the code, with continuous updates and improvements.

Documentation Structure

Project Documentation (In Individual Repositories)

Each project repository contains:

• README.md: Quick start, installation, and basic usage
• docs/ directory with:
• CONTRIBUTING.md: Contribution guidelines
• CHANGELOG.md: Version history
• Project-specific reference documentation

Centralized Documentation (In BFDOCS)

The centralized documentation provides a comprehensive view of the entire system:

• Architecture: System-wide architecture diagrams and explanations
• Guides: End-to-end processes and workflows
• Integration: How components interact with each other
• ML Documentation: ML model details and training information
• API Documentation: Complete API reference
• Setup: Environment setup instructions
• Project-Specific Documentation: Links to and summaries of individual project documentation

Documentation Standards

File Formats

• Use Markdown for all documentation
• Use PlantUML or Mermaid for diagrams (embedded in Markdown)
• Use YAML for structured data

Markdown Conventions

• Use ATX-style headings with a space after the hash marks: # Heading 1
• Use sentence case for headings: ## Installation guide (not ## Installation Guide)
• Maximum heading level: 4 (#### Heading 4)
• Use fenced code blocks with language specifiers: ```javascript
• Use relative links for internal documentation
• Use external links for third-party resources

Code Examples

• Include meaningful, working code examples
• Explain what the code does and why
• For complex examples, link to runnable examples in the codebase
• For API endpoints, include request/response examples

Screenshots and Images

• Use screenshots sparingly and only when necessary
• Avoid including UI elements that change frequently
• Use annotations when helpful
• Optimize images for web (compress PNG/JPG files)

Documentation Workflow

Creating New Documentation

1. Determine whether the documentation belongs in a project repository or in BFDOCS
2. If project-specific, create it in the project's docs/ directory
3. If system-wide, create it in the appropriate section of BFDOCS
4. Follow the style and format guidelines
5. Include cross-references to related documentation

Updating Documentation

1. Update project documentation alongside code changes
2. If the changes affect system-wide behavior, also update centralized documentation
3. Submit documentation changes as part of the same merge request as code changes
4. Include documentation updates in the merge request description

Documentation Review

Documentation undergoes the same review process as code:

1. Peer review for technical accuracy
2. Style and formatting check
3. Cross-reference verification
4. Consistency with existing documentation

Automation and Tooling

We use automation to maintain consistent documentation:

CI/CD Integration

• Documentation is built and published automatically
• Documentation is checked for broken links, formatting issues, etc.
• Project-specific documentation is synchronized with the central repository

Documentation Checks

Our CI/CD pipeline runs these checks:

1. Markdown linting
2. Link validation
3. Required sections check
4. Documentation structure verification

Documentation Tagging and Versions

• Documentation is versioned along with code
• Major releases have corresponding documentation versions
• Legacy documentation is preserved for previous versions

Getting Started with Documentation

For Developers

1. Project Documentation: When working on a project, update its documentation in the project repository.
2. Standards Compliance: Run the documentation check script to ensure standards compliance:

python /path/to/BFDOCS/scripts/check-doc-standards.py --project-path . --project-type <type>

1. Centralized Documentation: For system-wide changes, update the central BFDOCS repository.

For Documentation Contributors

1. Clone the BFDOCS repository:

git clone https://gitlab.com/bluefly/bfdocs.git
cd bfdocs

1. Make your changes following the guidelines in this document.
2. Preview your changes locally:

pip install mkdocs mkdocs-material
mkdocs serve

1. Submit a merge request with your changes.

Best Practices

1. Write for Your Audience: Consider who will read the documentation and what they need to know.
2. Keep It Current: Outdated documentation is worse than no documentation.
3. Show, Don't Tell: Use examples, diagrams, and code snippets.
4. Be Concise: Use simple language and avoid unnecessary words.
5. Cross-Reference: Link to related documentation for additional information.
6. Test Your Documentation: Verify that code examples work and instructions are accurate.
7. Get Feedback: Ask users if the documentation meets their needs.

Documentation Aggregation

Our documentation aggregation system automatically collects documentation from individual project repositories and includes it in the central documentation site:

1. CI/CD pipelines watch for changes to documentation in project repositories
2. When changes are detected, documentation is collected and copied to BFDOCS
3. BFDOCS builds the full documentation site with MkDocs
4. The site is deployed to GitLab Pages

Documentation Organization

Suggested Project Documentation Structure

project-root/
├── README.md
├── docs/
│   ├── CONTRIBUTING.md
│   ├── CHANGELOG.md
│   ├── api/
│   │   └── reference.md
│   ├── getting-started/
│   │   └── index.md
│   ├── integration/
│   │   └── index.md
│   ├── deployment/
│   │   └── index.md
│   └── [project-specific-directories]/
└── [project files]

Centralized Documentation Structure

BFDOCS/
├── README.md
├── mkdocs.yml
├── docs/
│   ├── index.md
│   ├── architecture/
│   ├── guides/
│   ├── integration/
│   ├── ml/
│   ├── api/
│   ├── setup/
│   └── projects/
│       ├── bfcicomponents.md
│       ├── bfmodel.md
│       ├── bfapi.md
│       ├── bfcli.md
│       ├── bfui.md
│       ├── bfrfp.md
│       └── bluefly_insights.md
├── assets/
└── scripts/

Metrics and Improvement

We track the following documentation metrics:

1. Documentation coverage (percentage of features documented)
2. Documentation quality (based on automated checks)
3. Documentation freshness (time since last update)
4. User feedback (gathered through surveys and issue tracking)

These metrics help us identify areas for improvement and ensure our documentation remains helpful and current.

Help and Support

If you have questions about documentation or need help, please:

1. Open an issue in the BFDOCS repository
2. Reach out to the documentation team on Slack
3. Email [email protected]