218 lines
6.1 KiB
Markdown
218 lines
6.1 KiB
Markdown
# 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:**
|
|
1. Merge approved documentation into main branch
|
|
2. Run automated build process
|
|
3. Deploy to documentation site
|
|
4. Verify published documentation
|
|
5. 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
|
|
```markdown
|
|
## 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:
|
|
|
|
1. Reviewers and author discuss directly
|
|
2. If unresolved, documentation lead mediates
|
|
3. Technical disagreements defer to subject matter experts
|
|
4. Style disagreements defer to style guide maintainer
|
|
5. Final decision rests with documentation lead
|
|
|
|
---
|
|
|
|
*This review process is maintained by the BMAD Documentation Team. Last updated: Current Date.*
|