mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-06 16:31:12 +08:00
Add comprehensive documentation templates and schemas for project documentation workflow
- Introduced agent instruction template for generating documentation tasks. - Created CSV schema for tasks including definitions and example entries. - Defined documentation dimensions across five waves with specific focus areas. - Established quality standards for documentation, including completeness, accuracy, clarity, and context integration.
This commit is contained in:
@@ -0,0 +1,195 @@
|
||||
# Quality Standards for Documentation
|
||||
|
||||
Quality assessment criteria for generated documentation.
|
||||
|
||||
---
|
||||
|
||||
## Quality Dimensions
|
||||
|
||||
### 1. Completeness (30%)
|
||||
|
||||
| Score | Criteria |
|
||||
|-------|----------|
|
||||
| 100% | All required sections present, all topics covered |
|
||||
| 80% | All sections present, some topics incomplete |
|
||||
| 60% | Most sections present, some missing |
|
||||
| 40% | Several sections missing |
|
||||
| 0% | Major sections absent |
|
||||
|
||||
**Checklist per Document**:
|
||||
- [ ] All sections in `doc_sections` are present
|
||||
- [ ] Each section has substantial content (not just placeholders)
|
||||
- [ ] Cross-references to related documentation
|
||||
- [ ] Code examples where applicable
|
||||
- [ ] Diagrams where applicable
|
||||
|
||||
### 2. Accuracy (25%)
|
||||
|
||||
| Score | Criteria |
|
||||
|-------|----------|
|
||||
| 100% | All information correct, file references accurate |
|
||||
| 80% | Minor inaccuracies, most references correct |
|
||||
| 60% | Some errors, most file references work |
|
||||
| 40% | Multiple errors, broken references |
|
||||
| 0% | Significant inaccuracies |
|
||||
|
||||
**Checklist**:
|
||||
- [ ] Code examples compile/run correctly
|
||||
- [ ] File paths and line numbers are accurate
|
||||
- [ ] API signatures match actual implementation
|
||||
- [ ] Configuration examples are valid
|
||||
- [ ] Dependencies and versions are correct
|
||||
|
||||
### 3. Clarity (25%)
|
||||
|
||||
| Score | Criteria |
|
||||
|-------|----------|
|
||||
| 100% | Clear, concise, well-organized, easy to navigate |
|
||||
| 80% | Clear, minor organization issues |
|
||||
| 60% | Understandable but could be clearer |
|
||||
| 40% | Confusing in places |
|
||||
| 0% | Unclear, hard to follow |
|
||||
|
||||
**Checklist**:
|
||||
- [ ] Logical flow and organization
|
||||
- [ ] Clear headings and subheadings
|
||||
- [ ] Appropriate level of detail
|
||||
- [ ] Well-formatted code blocks
|
||||
- [ ] Readable diagrams
|
||||
|
||||
### 4. Context Integration (20%)
|
||||
|
||||
| Score | Criteria |
|
||||
|-------|----------|
|
||||
| 100% | Builds on previous waves, references earlier findings |
|
||||
| 80% | Good context usage, minor gaps |
|
||||
| 60% | Some context usage, could be more |
|
||||
| 40% | Limited context usage |
|
||||
| 0% | No context from previous waves |
|
||||
|
||||
**Checklist**:
|
||||
- [ ] References findings from context_from tasks
|
||||
- [ ] Uses discoveries.ndjson
|
||||
- [ ] Cross-references related documentation
|
||||
- [ ] Builds on previous wave outputs
|
||||
- [ ] Maintains consistency across documents
|
||||
|
||||
---
|
||||
|
||||
## Quality Gates (Per-Wave)
|
||||
|
||||
| Wave | Gate Criteria | Required Completion |
|
||||
|------|--------------|---------------------|
|
||||
| 1 | Overview + Tech Stack + Directory | 3/3 completed |
|
||||
| 2 | Architecture docs with diagrams | ≥3/4 completed |
|
||||
| 3 | Implementation details with code | ≥3/4 completed |
|
||||
| 4 | Feature + Usage + API docs | ≥2/3 completed |
|
||||
| 5 | Synthesis with README | 3/3 completed |
|
||||
|
||||
---
|
||||
|
||||
## Document Quality Metrics
|
||||
|
||||
| Metric | Target | Measurement |
|
||||
|--------|--------|-------------|
|
||||
| Section coverage | 100% | Required sections present |
|
||||
| Code example density | ≥1 per major topic | Code blocks per section |
|
||||
| File reference accuracy | ≥95% | Valid file:line references |
|
||||
| Cross-reference density | ≥2 per document | Links to other docs |
|
||||
| Diagram presence | Required for architecture | Diagrams in arch docs |
|
||||
|
||||
---
|
||||
|
||||
## Issue Severity Levels
|
||||
|
||||
### Critical (Must Fix)
|
||||
- Missing required section
|
||||
- Broken cross-references
|
||||
- Incorrect API documentation
|
||||
- Code examples that don't work
|
||||
- File references to non-existent files
|
||||
|
||||
### High (Should Fix)
|
||||
- Incomplete section content
|
||||
- Minor inaccuracies
|
||||
- Missing diagrams in architecture docs
|
||||
- Outdated dependency versions
|
||||
- Unclear explanations
|
||||
|
||||
### Medium (Nice to Fix)
|
||||
- Formatting issues
|
||||
- Suboptimal organization
|
||||
- Missing optional content
|
||||
- Minor typos
|
||||
|
||||
### Low (Optional)
|
||||
- Style consistency
|
||||
- Additional examples
|
||||
- More detailed explanations
|
||||
|
||||
---
|
||||
|
||||
## Quality Scoring
|
||||
|
||||
### Per-Document Score
|
||||
|
||||
```
|
||||
Score = (Completeness × 0.30) + (Accuracy × 0.25) + (Clarity × 0.25) + (Context × 0.20)
|
||||
```
|
||||
|
||||
### Overall Session Score
|
||||
|
||||
```
|
||||
Score = Σ(Document Score × Weight) / Σ(Weights)
|
||||
```
|
||||
|
||||
**Weights by Wave**:
|
||||
| Wave | Weight | Rationale |
|
||||
|------|--------|-----------|
|
||||
| 1 | 1.0 | Foundation |
|
||||
| 2 | 1.5 | Core architecture |
|
||||
| 3 | 1.5 | Implementation depth |
|
||||
| 4 | 1.0 | User-facing |
|
||||
| 5 | 2.0 | Synthesis quality |
|
||||
|
||||
### Quality Thresholds
|
||||
|
||||
| Score | Status | Action |
|
||||
|-------|--------|--------|
|
||||
| ≥85% | PASS | Ready for delivery |
|
||||
| 70-84% | REVIEW | Flag for improvement |
|
||||
| <70% | FAIL | Block, require re-generation |
|
||||
|
||||
---
|
||||
|
||||
## Documentation Style Guide
|
||||
|
||||
### Markdown Standards
|
||||
- Use ATX headings (# ## ###)
|
||||
- Code blocks with language hints
|
||||
- Mermaid for diagrams
|
||||
- Tables for structured data
|
||||
|
||||
### Code Reference Format
|
||||
```
|
||||
src/module/file.ts:42-56
|
||||
```
|
||||
|
||||
### Cross-Reference Format
|
||||
```markdown
|
||||
See: [Document Title](path/to/doc.md#section)
|
||||
```
|
||||
|
||||
### LaTeX Format (when formula_support=true)
|
||||
```markdown
|
||||
$$
|
||||
\frac{\partial u}{\partial t} = \nabla^2 u
|
||||
$$
|
||||
```
|
||||
|
||||
### Diagram Format
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Start] --> B[Process]
|
||||
B --> C[End]
|
||||
```
|
||||
Reference in New Issue
Block a user