Skip to main content

Contributing to Documentation

🎯 How to Report Issues​

1. Documentation Bugs​

Use the "Documentation Bug Report" template when you find:

  • Incorrect information
  • Broken links
  • Typos or grammatical errors
  • Inconsistent formatting
  • Missing or outdated content

2. Documentation Improvements​

Use the "Documentation Improvement" template for:

  • Suggestions to make content clearer
  • Requests for additional examples
  • Proposals for better organization
  • Enhancement ideas

3. Documentation TODOs​

Use the "Documentation TODO" template for:

  • New documentation that needs to be created
  • Missing sections in existing docs
  • Content that needs to be updated or expanded

🤖 AI-Assisted Documentation​

How to Use AI Assistance​

  1. Create an issue using the appropriate template
  2. Add the llm-ready label when you want AI assistance
  3. The AI will analyze the issue and provide detailed recommendations
  4. Review the recommendations and ask questions if needed
  5. Implement changes manually based on the AI suggestions
  6. Update the issue with progress or mark as resolved

AI Capabilities​

Our AI assistant can help with:

  • ✅ Analyzing documentation issues and providing detailed recommendations
  • ✅ Suggesting specific fixes for bugs and inconsistencies
  • ✅ Recommending improvements for clarity and readability
  • ✅ Providing content structure for new documentation
  • ✅ Ensuring consistency with existing style guidelines
  • ✅ Suggesting examples and code snippets to include
  • ✅ Identifying related documentation that might need updates

AI Limitations​

The AI assistant provides recommendations but:

  • ❌ Does not make changes directly - all changes are implemented manually
  • ❌ Cannot test code examples - human review and testing required
  • ❌ Cannot access private information - only works with public repository content
  • ❌ Provides suggestions only - final decisions remain with humans

📝 Writing Guidelines​

Style and Tone​

  • Clear and concise: Use simple, direct language
  • Consistent: Follow established patterns and terminology
  • User-focused: Write from the user's perspective
  • Actionable: Provide clear steps and examples

Structure​

  • Use descriptive headings
  • Include overview sections
  • Provide step-by-step instructions
  • Add troubleshooting sections when relevant
  • Include related links and resources

Code Examples​

  • Use syntax highlighting
  • Include comments explaining key parts
  • Test all code examples
  • Provide both simple and advanced examples
  • Include expected outputs when helpful

🏷️ Labeling System​

Essential Labels​

Type Labels:

  • documentation: All documentation-related issues
  • bug: Something is incorrect or broken
  • enhancement: Improvement or new feature
  • todo: Task that needs to be completed

Status Labels:

  • in-progress: Currently being worked on
  • llm-ready: Ready for AI assistance

Priority Labels:

  • priority-high: Critical issues affecting users
  • priority-low: Nice-to-have enhancements

🔄 Workflow​

For Contributors​

  1. Find an issue you want to work on
  2. Comment on the issue to claim it
  3. Create a branch from main
  4. Make your changes following the style guide
  5. Test your changes locally
  6. Create a pull request with a clear description
  7. Request review from maintainers

For AI Assistance​

  1. Create an issue with detailed description
  2. Add llm-ready label when ready for AI help
  3. Review AI recommendations and ask questions if needed
  4. Implement changes manually based on AI suggestions
  5. Test and update the issue with progress

📋 Review Checklist​

Before submitting documentation changes:

  • Content is accurate and up-to-date
  • Writing is clear and follows style guide
  • Code examples are tested and working
  • Links are valid and relevant
  • Formatting is consistent
  • No typos or grammatical errors
  • Includes appropriate examples
  • Has been tested locally

🆘 Getting Help​

  • Ask questions in issue comments
  • Tag maintainers for urgent issues
  • Use the help-wanted label for complex tasks
  • Check existing issues before creating duplicates

📚 Resources​