BMAD-METHOD/docs/documentation-standards/contribution-guidelines.md

BMAD Documentation Contribution Guidelines

Overview

This document outlines the process for contributing to the BMAD Method documentation. Following these guidelines ensures a smooth review process and maintains the high quality of our documentation.

Getting Started

Prerequisites

• GitHub account
• Basic knowledge of Markdown
• Familiarity with the BMAD Method
• Understanding of the documentation structure

Setting Up Your Environment

1. Fork the BMAD Documentation repository
2. Clone your fork locally
3. Install dependencies:

   npm install
   

4. Set up pre-commit hooks:

   npm run prepare
   

Contribution Process

1. Find or Create an Issue

• Check existing issues in the issue tracker
• If your contribution doesn't match an existing issue, create a new one
• Wait for issue assignment or approval before starting work

2. Create a Branch

• Create a branch from main with a descriptive name:

  git checkout -b doc/add-developer-guide
  

• Use prefixes to indicate the type of change:
  • doc/ for documentation additions
  • fix/ for documentation fixes
  • update/ for documentation updates
  • review/ for review changes

3. Make Your Changes

• Follow the Style Guide
• Run automated checks locally:

  npm run lint:all
  

• Test your changes by building the documentation locally:

  npm run docs:build
  npm run docs:serve
  

4. Commit Your Changes

• Use conventional commit messages:

  docs(persona): add developer integration guide
  
  - Add detailed setup instructions
  - Include code examples
  - Add troubleshooting section
  
  Closes #123
  

• Keep commits focused and atomic
• Reference issues in commit messages

5. Submit a Pull Request

• Push your branch to your fork
• Create a pull request against the main branch
• Fill out the pull request template completely
• Request review from appropriate team members
• Address review feedback promptly

6. Review Process

All contributions go through a review process:

1. Automated Checks: CI/CD pipeline runs linting, spelling, and link validation
2. Peer Review: At least one team member reviews the content
3. Technical Review: Subject matter experts verify technical accuracy
4. Final Approval: Documentation maintainer approves and merges

Documentation Types

New Documentation

When creating new documentation:

1. Use the appropriate template from the templates/ directory
2. Follow the established directory structure
3. Include all required sections
4. Add entry to navigation if applicable
5. Create examples where appropriate

Updates to Existing Documentation

When updating existing documentation:

1. Maintain the existing structure and style
2. Clearly mark deprecated content
3. Update related documentation as needed
4. Update the "Last Updated" date
5. Add changelog entry if significant

Translations

When contributing translations:

1. Create files in the appropriate language directory
2. Maintain the same structure as the English version
3. Include language code in filename (e.g., quickstart.fr.md)
4. Update language selector in navigation

Best Practices

Content Guidelines

• Write for an international audience
• Use simple, clear language
• Provide context and examples
• Link to related documentation
• Include troubleshooting sections
• Consider the user's perspective and needs

Technical Guidelines

• Test all code examples
• Verify command outputs
• Check compatibility across environments
• Include version information
• Provide alternative approaches where applicable

Review Guidelines

• Be constructive and specific in feedback
• Suggest improvements rather than just pointing out issues
• Consider the author's intent
• Focus on content quality and accuracy
• Be timely in your reviews

Recognition

Contributors are recognized in several ways:

• Listed in the Contributors file
• Mentioned in release notes
• Acknowledged in the documentation they contributed to

Code of Conduct

All contributors must adhere to our Code of Conduct. We are committed to providing a welcoming and inclusive environment for all contributors.

Questions and Support

If you have questions about contributing:

• Join our Community Slack
• Email the documentation team at docs@bmad-method.org
• Ask in the #documentation channel on Slack
• Check the FAQ for common questions

---

These contribution guidelines are maintained by the BMAD Documentation Team. Last updated: Current Date.