Skip to content

Documentation Workflow Guide

This guide explains how documentation is managed across the Bluefly LLM ecosystem to ensure it remains up-to-date, consistent, and easily accessible.

Overview

The Bluefly LLM ecosystem uses a hybrid documentation approach:

  1. Project-specific documentation lives in each repository, allowing developers to update docs alongside code changes
  2. Central documentation hub (BFDOCS) aggregates all documentation into a single, searchable website

This approach ensures that: - Documentation can be updated by developers as part of their normal workflow - Changes to code and documentation can be reviewed together - A comprehensive, centralized resource is always available

Documentation Structure

Each project should maintain its documentation using the following structure:

project-root/
├── README.md              # Project overview and quick start
├── CLAUDE.md              # Implementation guidance for Claude AI
├── docs/                  # Detailed documentation
│   ├── api/               # API reference docs (if applicable)
│   ├── technical/         # Technical implementation details
│   └── user/              # User guides (if applicable)
├── other project files...

Documentation Synchronization

The documentation synchronization process works as follows:

  1. Documentation is written and maintained in each project's repository
  2. BFDOCS automatically pulls the documentation from each project through:
  3. Scheduled synchronization jobs (daily)
  4. Webhook triggers when changes are pushed to main branches
  5. Manual synchronization when needed

The synchronization process: - Preserves the original content - Adjusts internal links to work in the centralized context - Creates proper navigation structure - Ensures consistent formatting

How to Update Documentation

For Project-Specific Updates

  1. Edit documentation files in your project repository
  2. Test and review the changes locally
  3. Commit and push to your branch
  4. Create a merge request
  5. After the merge request is approved and merged, documentation will be automatically synchronized to BFDOCS

Triggering Manual Synchronization

If you need to trigger a manual synchronization:

  1. Go to the BFDOCS repository
  2. Create a new branch
  3. Push a commit with the message including [sync docs]
  4. Create a merge request

Checking Synchronization Status

You can check the status of documentation synchronization:

  1. Look at the _sync.json file in each project's documentation directory in BFDOCS
  2. Check the CI/CD pipeline status of the BFDOCS project

Best Practices

Writing Documentation

  • Keep documentation close to code: Document features and components in the same repository
  • Use Markdown format: All documentation should be written in Markdown
  • Include examples: Provide practical examples wherever possible
  • Cross-reference: Link to related documentation when appropriate
  • Maintain structure: Follow the established directory structure
  • Use relative links within project: Links to other files within the same project should be relative
  • Use absolute links for cross-project references: When linking to other projects, use the full BFDOCS path

Documentation Reviews

  • Documentation changes should be reviewed as part of code reviews
  • Check for technical accuracy, completeness, and clarity
  • Ensure links work correctly
  • Verify that the format follows the guidelines

Troubleshooting

If documentation is not being properly synchronized:

  1. Check the CI/CD logs for sync-documentation job failures
  2. Verify that your documentation structure follows the conventions
  3. Ensure all Markdown files have proper formatting
  4. If problems persist, manually trigger a synchronization with [sync docs] commit message

Getting Help

If you encounter issues with documentation:

  1. Check the existing issues in the BFDOCS repository
  2. Create a new issue if needed
  3. Contact the documentation team for assistance