6.1 KiB
6.1 KiB
BMAD Documentation Review Process
Overview
This document outlines the review process for all BMAD Method documentation. A thorough review process ensures our documentation is accurate, consistent, and valuable to users.
Review Roles
Author
- Creates or updates documentation
- Responds to feedback
- Makes requested changes
- Ensures documentation meets standards
Technical Reviewer
- Verifies technical accuracy
- Tests procedures and examples
- Ensures compatibility with current versions
- Validates architectural decisions
Documentation Reviewer
- Checks style guide compliance
- Reviews structure and organization
- Ensures consistency with existing documentation
- Verifies accessibility and readability
Final Approver
- Performs final quality check
- Ensures all review feedback is addressed
- Approves merging into main documentation
- Publishes documentation updates
Review Workflow
1. Pre-Review Preparation
Author Responsibilities:
- Run automated checks (linting, spelling, links)
- Self-review against style guide
- Complete the pre-review checklist
- Request review in the documentation system
Pre-Review Checklist:
- Documentation follows the style guide
- All automated checks pass
- Code examples are tested and working
- Images have alt text
- Links are valid
- No placeholder content remains
- Proper headers and structure used
- Spell check completed
2. Technical Review
Technical Reviewer Responsibilities:
- Verify technical accuracy of all content
- Test all procedures on a clean environment
- Validate code examples and commands
- Check compatibility with specified versions
- Review architectural recommendations
- Provide feedback within 3 business days
Technical Review Checklist:
- All technical information is accurate
- Procedures work as described
- Code examples execute correctly
- Technical terminology is used correctly
- Security best practices are followed
- Performance considerations are addressed
- Edge cases are considered
- Technical diagrams are accurate
3. Documentation Review
Documentation Reviewer Responsibilities:
- Check compliance with style guide
- Review structure and organization
- Ensure consistency with existing documentation
- Verify accessibility and readability
- Check cross-references and related documentation
- Provide feedback within 3 business days
Documentation Review Checklist:
- Follows style guide conventions
- Structure is logical and consistent
- Language is clear and concise
- Terminology is consistent
- Headers and sections are appropriate
- Formatting is consistent
- Accessibility guidelines are followed
- Cross-references are accurate
4. Revision
Author Responsibilities:
- Address all feedback from reviewers
- Track changes made in response to feedback
- Request re-review if significant changes were made
- Complete the revision checklist
Revision Checklist:
- All technical review feedback addressed
- All documentation review feedback addressed
- Automated checks still pass after changes
- No new issues introduced during revisions
- Changes documented in revision history
5. Final Approval
Final Approver Responsibilities:
- Verify all review feedback has been addressed
- Perform final quality check
- Ensure documentation meets all standards
- Approve merging into main documentation
- Update documentation version if applicable
Final Approval Checklist:
- All review feedback addressed
- Documentation meets quality standards
- Version information updated if applicable
- Release notes prepared if applicable
- Documentation ready for publication
6. Publication
Publication Process:
- Merge approved documentation into main branch
- Run automated build process
- Deploy to documentation site
- Verify published documentation
- Announce update if significant
Review Timeframes
- Technical Review: 3 business days
- Documentation Review: 3 business days
- Revision: Dependent on scope of changes
- Final Approval: 2 business days
- Emergency Updates: Expedited process available
Review Tools
GitHub Pull Request Reviews
- Use GitHub PR review features
- Add line-specific comments
- Use suggestion feature for small changes
- Link to relevant issues or documentation
Documentation Review Template
## Documentation Review
### Overall Assessment
- [ ] Approved
- [ ] Approved with changes
- [ ] Needs revision
### Technical Accuracy
[Comments on technical accuracy]
### Structure and Organization
[Comments on structure and organization]
### Style and Consistency
[Comments on style and consistency]
### Specific Feedback
1. [Page/Section]: [Feedback]
2. [Page/Section]: [Feedback]
### Additional Notes
[Any other comments or suggestions]
Special Review Cases
Major Documentation Updates
- Requires review from multiple technical experts
- May require user testing
- Consider phased rollout
- Create migration guide if applicable
Emergency Documentation Updates
- Expedited review process
- Focus on critical accuracy
- May bypass some review steps
- Must be reviewed fully after publication
Translation Reviews
- Requires native speaker review
- Technical reviewer must verify accuracy
- Check for cultural appropriateness
- Ensure consistent terminology across languages
Continuous Improvement
The review process itself is subject to continuous improvement:
- Collect metrics on review efficiency
- Gather feedback from authors and reviewers
- Regularly update review checklists
- Improve automation tools
- Review and update this process quarterly
Review Dispute Resolution
If disagreements arise during the review process:
- Reviewers and author discuss directly
- If unresolved, documentation lead mediates
- Technical disagreements defer to subject matter experts
- Style disagreements defer to style guide maintainer
- Final decision rests with documentation lead
This review process is maintained by the BMAD Documentation Team. Last updated: Current Date.