234 lines
6.4 KiB
Markdown
234 lines
6.4 KiB
Markdown
# Documentation Convention Analysis for PR #826
|
|
|
|
Date: 2025-10-28
|
|
|
|
---
|
|
|
|
## Current BMAD Documentation Structure
|
|
|
|
### Root-Level Documentation (Highly Restricted)
|
|
|
|
```
|
|
bmad-v6/
|
|
├── README.md ← Project entry point, installation, quick start
|
|
├── CHANGELOG.md ← Version history
|
|
├── CONTRIBUTING.md ← Contribution guidelines
|
|
├── v6-open-items.md ← Internal development tracking (temp)
|
|
└── LICENSE ← License file
|
|
```
|
|
|
|
**Pattern**: Root `.md` files are limited to essential project metadata only.
|
|
|
|
### Documentation Organization (`docs/`)
|
|
|
|
```
|
|
docs/
|
|
├── bmad-brownfield-guide.md ← Guides (root of docs/)
|
|
├── v4-to-v6-upgrade.md ← Guides (root of docs/)
|
|
├── conversion-report-*.md ← Internal reports (root of docs/)
|
|
├── ide-info/ ← Category: IDE-specific guides
|
|
│ ├── auggie.md
|
|
│ ├── claude-code.md
|
|
│ ├── cursor.md
|
|
│ ├── windsurf.md
|
|
│ └── ... (13 IDE guides)
|
|
└── installers-bundlers/ ← Category: Technical internals
|
|
├── ide-injections.md
|
|
├── installers-modules-platforms-reference.md
|
|
└── web-bundler-usage.md
|
|
```
|
|
|
|
**Pattern**:
|
|
|
|
- Guides go directly in `docs/` root if broadly applicable
|
|
- Categorized subdirectories for specific topics (`ide-info/`, `installers-bundlers/`)
|
|
- Kebab-case filenames
|
|
|
|
### Missing Categories (Gaps)
|
|
|
|
Based on analysis, these logical categories don't yet exist:
|
|
|
|
- `docs/planning/` - Would fit planning guides
|
|
- `docs/guides/` - Could house methodology guides
|
|
- `docs/references/` - Could house reference materials
|
|
|
|
---
|
|
|
|
## Filename Convention Analysis
|
|
|
|
### Pattern Observed
|
|
|
|
**Root documentation** (3 files):
|
|
|
|
- `README.md` (standard)
|
|
- `CHANGELOG.md` (standard)
|
|
- `CONTRIBUTING.md` (standard)
|
|
- `v6-open-items.md` (internal, kebab-case)
|
|
|
|
**Docs directory** (all kebab-case):
|
|
|
|
- `bmad-brownfield-guide.md`
|
|
- `v4-to-v6-upgrade.md`
|
|
- `conversion-report-shard-doc-2025-10-26.md`
|
|
- `ide-injections.md`
|
|
- `installers-modules-platforms-reference.md`
|
|
- `web-bundler-usage.md`
|
|
|
|
**IDE info** (all kebab-case):
|
|
|
|
- `claude-code.md`
|
|
- `github-copilot.md`
|
|
- `auggie.md`, etc.
|
|
|
|
**Verdict**: 100% consistent **kebab-case** for all documentation files.
|
|
|
|
### PR #826 Filename
|
|
|
|
- **Proposed**: `high-level-product-plan.md`
|
|
- **Evaluation**: ✅ Follows kebab-case convention
|
|
- **Issue**: Name is vague; doesn't indicate it's a checklist/guide
|
|
|
|
**Better alternatives**:
|
|
|
|
- `product-planning-checklist.md`
|
|
- `product-planning-considerations.md`
|
|
- `planning-reference.md`
|
|
|
|
---
|
|
|
|
## Content Pattern Analysis
|
|
|
|
### Existing Documentation Characteristics
|
|
|
|
**BMAD Guides** (e.g., `bmad-brownfield-guide.md`):
|
|
|
|
- Explain BMAD methodology application
|
|
- Reference BMAD levels, phases, workflows
|
|
- Show CLI commands (`bmad pm`, agent triggers)
|
|
- Link to specific workflows and agents
|
|
- Practical, BMAD-integrated advice
|
|
|
|
**Technical References** (e.g., `installers-modules-platforms-reference.md`):
|
|
|
|
- Deep technical implementation details
|
|
- Architecture diagrams
|
|
- Code examples from BMAD codebase
|
|
- Installation and configuration specifics
|
|
|
|
**Upgrade Guides** (e.g., `v4-to-v6-upgrade.md`):
|
|
|
|
- Migration instructions
|
|
- Before/after comparisons
|
|
- BMAD workflow mapping
|
|
- Specific commands and file locations
|
|
|
|
### PR #826 Content Characteristics
|
|
|
|
- Generic software planning checklist
|
|
- No BMAD methodology references
|
|
- No agent/workflow integration
|
|
- No CLI commands
|
|
- Could apply to any software project
|
|
- Reads like external reference material
|
|
|
|
**Mismatch**: Content doesn't follow BMAD documentation pattern of methodology integration.
|
|
|
|
---
|
|
|
|
## Overlap Analysis
|
|
|
|
### Existing BMAD Planning Documentation
|
|
|
|
**In `src/modules/bmm/workflows/`**:
|
|
|
|
- `2-plan-workflows/` - Contains PRD, tech-spec, architecture workflows
|
|
- `2-plan-workflows/README.md` - Explains BMAD planning phases
|
|
- Individual workflow docs explain specific planning activities
|
|
|
|
**In `docs/`**:
|
|
|
|
- `bmad-brownfield-guide.md` - Covers planning considerations for existing projects
|
|
- `v4-to-v6-upgrade.md` - Mentions planning phase (PRD/Architecture)
|
|
|
|
**PR #826 Coverage**:
|
|
Sections 1-8 overlap significantly with existing BMAD concepts:
|
|
|
|
1. Product Architecture → BMAD `architect` agent, architecture workflow
|
|
2. Technology Stack → Part of tech-spec workflow
|
|
3. Infrastructure & Deployment → Part of architecture planning
|
|
4. Data & Security → Part of tech-spec and architecture
|
|
5. User Experience → Covered in UX workflows
|
|
6. Scalability & Performance → Architecture considerations
|
|
7. Business & Operations → Part of project brief/PRD
|
|
8. Development Process → BMM workflow methodology
|
|
|
|
**Verdict**: ⚠️ High overlap with existing BMAD workflow coverage, but presented generically without BMAD integration.
|
|
|
|
---
|
|
|
|
## Recommendations
|
|
|
|
### Option 1: Relocate to `docs/planning/` (Recommended)
|
|
|
|
**Path**: `docs/planning/product-planning-checklist.md`
|
|
|
|
**Rationale**:
|
|
|
|
- Creates logical category for planning guides
|
|
- Consistent with docs categorization pattern
|
|
- Clear, specific filename
|
|
- Allows for future planning guides
|
|
|
|
**Required changes**:
|
|
|
|
1. Create `docs/planning/` directory
|
|
2. Move file with better name
|
|
3. Add BMAD integration section
|
|
4. Link to relevant workflows
|
|
|
|
### Option 2: Integrate into Existing Guide
|
|
|
|
**Path**: Merge into `docs/bmad-brownfield-guide.md` as appendix
|
|
|
|
**Rationale**:
|
|
|
|
- Brownfield guide already covers planning considerations
|
|
- Avoids duplication
|
|
- Contextualizes within BMAD methodology
|
|
|
|
**Required changes**:
|
|
|
|
1. Add as "Appendix: Comprehensive Planning Checklist"
|
|
2. Reference BMAD agents/workflows for each section
|
|
3. Maintain single planning guide
|
|
|
|
### Option 3: Enhance and Place at `docs/product-planning-with-bmad.md`
|
|
|
|
**Path**: `docs/product-planning-with-bmad.md`
|
|
|
|
**Rationale**:
|
|
|
|
- Top-level guide visibility
|
|
- Rewrite to be BMAD-first
|
|
- Transform generic checklist into BMAD methodology guide
|
|
|
|
**Required changes**:
|
|
|
|
1. Extensive rewrite with BMAD integration
|
|
2. Add agent/workflow references throughout
|
|
3. Include CLI examples
|
|
4. Link to specific workflow docs
|
|
|
|
---
|
|
|
|
## Conclusion
|
|
|
|
**Convention Compliance**:
|
|
|
|
- ✅ Filename: Kebab-case (matches pattern)
|
|
- ❌ Placement: Root violation (should be in `docs/`)
|
|
- ❌ Content: Generic (should integrate BMAD)
|
|
- ⚠️ Organization: Missing logical category (suggest creating `docs/planning/`)
|
|
|
|
**Recommended Action**: Request relocation to `docs/planning/product-planning-checklist.md` with optional BMAD enhancement suggestions.
|