Skip to content

Maintaining Documentation Across Bluefly Projects

This guide provides practical advice for maintaining documentation across the Bluefly LLM ecosystem. It's intended for developers and technical writers who need to create, update, or manage documentation.

Documentation Lifecycle

Documentation in the Bluefly ecosystem follows this lifecycle:

  1. Creation: Documentation is written alongside code
  2. Review: Documentation undergoes technical and editorial review
  3. Publication: Documentation is published to the central site
  4. Maintenance: Documentation is kept up-to-date with code changes
  5. Retirement: Obsolete documentation is archived or removed

Project-Specific vs. Centralized Documentation

Understanding what belongs where is crucial for maintaining a coherent documentation system:

Project-Specific Documentation (In Project Repositories)

  • Installation and setup instructions
  • API reference specific to the project
  • Code examples specific to the project
  • Contribution guidelines
  • Changelog

Centralized Documentation (In BFDOCS)

  • System architecture and component interactions
  • End-to-end workflows involving multiple components
  • General concepts and glossary
  • Integration guidelines
  • User guides for the entire ecosystem
  • Tutorials spanning multiple components

Updating Documentation

When to Update Documentation

Documentation should be updated:

  1. When adding new features
  2. When changing existing functionality
  3. When fixing bugs that affect documented behavior
  4. When improving clarity or correcting errors
  5. When restructuring the system or code

How to Update Documentation

Project Documentation Updates

  1. Identify the appropriate document(s) to update
  2. Make your changes, following the style guidelines
  3. Test any code examples or commands
  4. Submit the documentation changes as part of your merge request
  5. Address any review feedback

Centralized Documentation Updates

  1. Clone the BFDOCS repository: 

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

  2. Create a branch for your changes: 

    git checkout -b docs/update-feature-x

  3. Make your changes

  4. Test the documentation locally: 

    mkdocs serve

  5. Submit a merge request

Documentation Change Examples

Example 1: Adding a New API Endpoint

  1. Project Repository:
  2. Update the API reference in the project's docs/api/ directory
  3. Add code examples

  4. Update changelog

  5. BFDOCS:

  6. If this is a major feature, update relevant guides or tutorials
  7. Update API overview if necessary

Example 2: Changing a Core System Component

  1. Project Repository:
  2. Update the component's documentation
  3. Update usage examples

  4. Update changelog

  5. BFDOCS:

  6. Update architecture documentation
  7. Update integration guides
  8. Update any affected tutorials or workflows

Using the Documentation Tooling

Checking Documentation Standards

Run the documentation standards check to ensure your documentation meets the Bluefly guidelines:

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

Available project types: common, api, ui, model, cli, rfp, drupal

Updating Project Documentation Structure

To update a project's documentation structure to match Bluefly standards:

node /path/to/BFDOCS/scripts/update-project-docs.js --type=<project-type>

This script will: 1. Create the necessary directory structure 2. Add template documentation files 3. Customize templates with project-specific information

Previewing Documentation Locally

To preview documentation before submitting changes:

# Install MkDocs
pip install mkdocs mkdocs-material

# Preview project documentation
cd /path/to/BFDOCS
mkdocs serve

Visit http://localhost:8000 to see the documentation site.

Documentation Aggregation System

Our documentation aggregation system automatically synchronizes documentation between project repositories and the central BFDOCS repository.

How It Works

  1. Project CI/CD pipelines detect changes to documentation files
  2. The sync-docs job in the project's CI/CD pipeline copies documentation to BFDOCS
  3. The BFDOCS CI/CD pipeline builds and deploys the complete documentation site

Triggering Documentation Updates

Documentation updates are triggered automatically when:

  1. Changes are made to the README.md file
  2. Changes are made to files in the docs/ directory
  3. A commit message contains docs:, documentation:, or update docs
  4. A new version tag is pushed (e.g., v1.2.3)

You can also manually trigger a documentation update:

# From a project repository
python /path/to/BFDOCS/scripts/sync_project_docs.py --project $(basename $(pwd)) --direction to_central

# From the BFDOCS repository
python scripts/sync_project_docs.py --project PROJECT_NAME --direction from_central

Common Documentation Tasks

Creating New Documentation

  1. Determine whether the documentation belongs in a project repository or BFDOCS
  2. Use the appropriate template from the BFDOCS/templates/ directory
  3. Follow the style guidelines
  4. Include all necessary sections (overview, usage, examples, etc.)
  5. Add the documentation to the appropriate location

Restructuring Existing Documentation

  1. Create a plan for the new structure
  2. Discuss major restructuring with the team
  3. Create a merge request with the proposed changes
  4. Update any cross-references
  5. Update the navigation in mkdocs.yml if necessary

Archiving Outdated Documentation

  1. Identify documentation that is no longer relevant
  2. If completely obsolete, remove it with a clear commit message
  3. If still useful for legacy purposes, move it to an archive/ directory
  4. Update any references to the archived documentation

Documentation Review Process

All documentation changes undergo review:

  1. Technical Accuracy: Is the information correct?
  2. Completeness: Does it cover all necessary aspects?
  3. Clarity: Is it easy to understand?
  4. Consistency: Does it follow our standards and terminology?
  5. Structure: Is it organized logically?

Review Checklist

When reviewing documentation, check for:

  • Technical accuracy
  • Completeness
  • Clear and concise language
  • Correct formatting
  • Working code examples
  • Valid links
  • Proper cross-references
  • Consistent terminology
  • Correct spelling and grammar
  • Adherence to style guidelines

Documentation Versioning

Documentation is versioned alongside code:

  1. Major versions have corresponding documentation versions
  2. Version-specific documentation is maintained with branches
  3. The latest documentation is always available at the main site
  4. Older versions are accessible through version selection

Version-Specific Documentation

To create version-specific documentation:

  1. Create a branch from the appropriate release tag: 

    git checkout -b docs/v1.2.x v1.2.0

  2. Make any documentation changes specific to that version

  3. Push the branch and create a merge request
  4. The CI/CD pipeline will publish the version-specific documentation

Troubleshooting Common Issues

Missing or Outdated Documentation

Symptoms: Documentation is missing or does not match current functionality.

Solution: 1. Identify the affected documentation 2. Update it to match the current code 3. If documentation is missing, create it using the appropriate template 4. Submit a merge request

Symptoms: Links in documentation lead to 404 errors or incorrect pages.

Solution: 1. Run the documentation link checker: 

python /path/to/BFDOCS/scripts/check_doc_consistency.py
2. Fix any broken links 3. Update any references to renamed or moved documents

Documentation Build Failures

Symptoms: Documentation fails to build in the CI/CD pipeline.

Solution: 1. Check the CI/CD logs for specific errors 2. Common issues include: - Malformed Markdown - Invalid YAML in mkdocs.yml - Missing referenced files - Syntax errors in code examples 3. Fix the issues and submit a new merge request

Best Practices for Specific Documentation Types

API Documentation

  • Use consistent formatting for all endpoints
  • Include request and response examples
  • Document all parameters
  • Specify authentication requirements
  • Include error handling information

User Guides

  • Write from the user's perspective
  • Include step-by-step instructions
  • Use screenshots where helpful
  • Explain why, not just how
  • Include troubleshooting sections

Architecture Documentation

  • Use diagrams to illustrate concepts
  • Explain design decisions
  • Document interactions between components
  • Keep diagrams and text in sync
  • Update when architecture changes

Conclusion

Maintaining documentation is an ongoing process that requires attention and care. By following these guidelines and using the provided tools, you can help ensure that the Bluefly LLM ecosystem documentation remains accurate, complete, and useful.

If you have questions or need assistance with documentation, please contact the documentation team or open an issue in the BFDOCS repository.