forked from jsnbuchanan/crowd-funder-for-time-pwa
feat: Add documentation meta-rule system with educational focus
- Create meta_documentation.mdc for comprehensive doc workflows - Add meta_rule_usage_guide.md for practical meta-rule usage - Enhance existing markdown rules with educational standards - Transform docs from technical reference to educational resources Emphasizes human competence over technical description, provides systematic workflows for all documentation tasks.
This commit is contained in:
Matthew Raymer
237
.cursor/rules/meta_documentation.mdc
Normal file
237
.cursor/rules/meta_documentation.mdc
Normal file
@@ -0,0 +1,237 @@
|
||||
# Meta-Rule: Documentation Writing & Education
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-08-21
|
||||
**Status**: 🎯 **ACTIVE** - Documentation writing and education workflow
|
||||
|
||||
## Purpose
|
||||
|
||||
This meta-rule bundles documentation-related rules to create comprehensive,
|
||||
educational documentation that increases human competence rather than just
|
||||
providing technical descriptions.
|
||||
|
||||
## When to Use
|
||||
|
||||
**Use this meta-rule when**:
|
||||
- Writing new documentation
|
||||
- Updating existing documentation
|
||||
- Creating technical guides
|
||||
- Writing migration documentation
|
||||
- Creating architectural documentation
|
||||
- Writing user guides or tutorials
|
||||
|
||||
## Bundled Rules
|
||||
|
||||
### **Core Documentation Standards**
|
||||
|
||||
- **`docs/markdown_core.mdc`** - Core markdown formatting and automation
|
||||
- **`docs/markdown_templates.mdc`** - Document templates and structure
|
||||
- **`docs/markdown_workflow.mdc`** - Documentation validation workflows
|
||||
|
||||
### **Documentation Principles**
|
||||
|
||||
- **`core/base_context.mdc`** - Human competence first principles
|
||||
- **`core/less_complex.mdc`** - Minimalist solution guidelines
|
||||
- **`development/software_development.mdc`** - Development documentation standards
|
||||
|
||||
### **Context-Specific Rules**
|
||||
|
||||
- **`app/timesafari.mdc`** - TimeSafari application context
|
||||
- **`app/timesafari_development.mdc`** - Development documentation patterns
|
||||
- **`architecture/architectural_patterns.mdc`** - Architecture documentation
|
||||
|
||||
## Core Documentation Philosophy
|
||||
|
||||
### **Education Over Technical Description**
|
||||
|
||||
**Primary Goal**: Increase human competence and understanding
|
||||
**Secondary Goal**: Provide accurate technical information
|
||||
**Approach**: Explain the "why" before the "how"
|
||||
|
||||
### **Human Competence Principles**
|
||||
|
||||
1. **Context First**: Explain the problem before the solution
|
||||
2. **Learning Path**: Structure content for progressive understanding
|
||||
3. **Real Examples**: Use concrete, relatable examples
|
||||
4. **Common Pitfalls**: Warn about typical mistakes and misconceptions
|
||||
5. **Decision Context**: Explain why certain choices were made
|
||||
|
||||
### **Documentation Hierarchy**
|
||||
|
||||
1. **Conceptual Understanding** - What is this and why does it matter?
|
||||
2. **Context and Motivation** - When and why would you use this?
|
||||
3. **Technical Implementation** - How do you implement it?
|
||||
4. **Examples and Patterns** - What does it look like in practice?
|
||||
5. **Troubleshooting** - What can go wrong and how to fix it?
|
||||
|
||||
## Implementation Guidelines
|
||||
|
||||
### **Document Structure**
|
||||
|
||||
**Mandatory Sections**:
|
||||
- **Overview**: Clear purpose and scope with educational context
|
||||
- **Why This Matters**: Business value and user benefit explanation
|
||||
- **Core Concepts**: Fundamental understanding before implementation
|
||||
- **Implementation**: Step-by-step technical guidance
|
||||
- **Examples**: Real-world usage patterns
|
||||
- **Common Issues**: Troubleshooting and prevention
|
||||
- **Next Steps**: Where to go from here
|
||||
|
||||
**Optional Sections**:
|
||||
- **Background**: Historical context and evolution
|
||||
- **Alternatives**: Other approaches and trade-offs
|
||||
- **Advanced Topics**: Deep dive into complex scenarios
|
||||
- **References**: Additional learning resources
|
||||
|
||||
### **Writing Style**
|
||||
|
||||
**Educational Approach**:
|
||||
- **Conversational tone**: Write as if explaining to a colleague
|
||||
- **Progressive disclosure**: Start simple, add complexity gradually
|
||||
- **Active voice**: "You can do this" not "This can be done"
|
||||
- **Question format**: "What happens when..." to engage thinking
|
||||
- **Analogies**: Use familiar concepts to explain complex ideas
|
||||
|
||||
**Technical Accuracy**:
|
||||
- **Precise language**: Use exact technical terms consistently
|
||||
- **Code examples**: Working, tested code snippets
|
||||
- **Version information**: Specify applicable versions and platforms
|
||||
- **Limitations**: Clearly state what the solution doesn't do
|
||||
|
||||
### **Content Quality Standards**
|
||||
|
||||
**Educational Value**:
|
||||
- [ ] **Concept clarity**: Reader understands the fundamental idea
|
||||
- [ ] **Context relevance**: Reader knows when to apply the knowledge
|
||||
- [ ] **Practical application**: Reader can implement the solution
|
||||
- [ ] **Problem prevention**: Reader avoids common mistakes
|
||||
- [ ] **Next steps**: Reader knows where to continue learning
|
||||
|
||||
**Technical Accuracy**:
|
||||
- [ ] **Fact verification**: All technical details are correct
|
||||
- [ ] **Code validation**: Examples compile and run correctly
|
||||
- [ ] **Version compatibility**: Platform and version requirements clear
|
||||
- [ ] **Security consideration**: Security implications addressed
|
||||
- [ ] **Performance notes**: Performance characteristics documented
|
||||
|
||||
## Document Types and Templates
|
||||
|
||||
### **Technical Guides**
|
||||
|
||||
**Focus**: Implementation and technical details
|
||||
**Structure**: Problem → Solution → Implementation → Examples
|
||||
**Education**: Explain the "why" behind technical choices
|
||||
|
||||
### **Migration Documentation**
|
||||
|
||||
**Focus**: Process and workflow guidance
|
||||
**Structure**: Context → Preparation → Steps → Validation → Troubleshooting
|
||||
**Education**: Help users understand migration benefits and risks
|
||||
|
||||
### **Architecture Documentation**
|
||||
|
||||
**Focus**: System design and decision rationale
|
||||
**Structure**: Problem → Constraints → Alternatives → Decision → Implementation
|
||||
**Education**: Explain design trade-offs and decision factors
|
||||
|
||||
### **User Guides**
|
||||
|
||||
**Focus**: Task completion and user empowerment
|
||||
**Structure**: Goal → Prerequisites → Steps → Verification → Next Steps
|
||||
**Education**: Help users understand the system's capabilities
|
||||
|
||||
## Quality Assurance
|
||||
|
||||
### **Review Checklist**
|
||||
|
||||
**Educational Quality**:
|
||||
- [ ] **Clear learning objective**: What will the reader learn?
|
||||
- [ ] **Appropriate complexity**: Matches target audience knowledge
|
||||
- [ ] **Progressive disclosure**: Information builds logically
|
||||
- [ ] **Practical examples**: Real-world scenarios and use cases
|
||||
- [ ] **Common questions**: Anticipates and answers reader questions
|
||||
|
||||
**Technical Quality**:
|
||||
- [ ] **Accuracy**: All technical details verified
|
||||
- [ ] **Completeness**: Covers all necessary information
|
||||
- [ ] **Consistency**: Terminology and formatting consistent
|
||||
- [ ] **Currency**: Information is up-to-date
|
||||
- [ ] **Accessibility**: Clear for target audience
|
||||
|
||||
### **Validation Workflows**
|
||||
|
||||
1. **Content Review**: Subject matter expert review
|
||||
2. **Educational Review**: Learning effectiveness assessment
|
||||
3. **Technical Review**: Accuracy and completeness validation
|
||||
4. **User Testing**: Real user comprehension testing
|
||||
5. **Continuous Improvement**: Regular updates based on feedback
|
||||
|
||||
## Success Metrics
|
||||
|
||||
### **Educational Effectiveness**
|
||||
|
||||
- **Comprehension**: Users understand the concepts
|
||||
- **Application**: Users can implement the solutions
|
||||
- **Confidence**: Users feel capable and empowered
|
||||
- **Efficiency**: Users complete tasks faster
|
||||
- **Satisfaction**: Users find documentation helpful
|
||||
|
||||
### **Technical Quality**
|
||||
|
||||
- **Accuracy**: Zero technical errors
|
||||
- **Completeness**: All necessary information included
|
||||
- **Consistency**: Uniform style and format
|
||||
- **Maintainability**: Easy to update and extend
|
||||
- **Accessibility**: Clear for target audience
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
### **Educational Mistakes**
|
||||
|
||||
- **Assumption overload**: Assuming too much prior knowledge
|
||||
- **Information dump**: Overwhelming with details
|
||||
- **Context missing**: Not explaining why something matters
|
||||
- **Example poverty**: Insufficient practical examples
|
||||
- **Feedback missing**: No way to verify understanding
|
||||
|
||||
### **Technical Mistakes**
|
||||
|
||||
- **Outdated information**: Not keeping content current
|
||||
- **Incomplete coverage**: Missing important details
|
||||
- **Inconsistent terminology**: Using different terms for same concepts
|
||||
- **Poor examples**: Non-working or confusing code
|
||||
- **Missing validation**: No way to verify correctness
|
||||
|
||||
## Feedback and Improvement
|
||||
|
||||
### **Continuous Learning**
|
||||
|
||||
- **User feedback**: Collect and analyze user comments
|
||||
- **Usage metrics**: Track document usage and effectiveness
|
||||
- **Review cycles**: Regular content review and updates
|
||||
- **Community input**: Engage users in documentation improvement
|
||||
- **Best practices**: Stay current with documentation standards
|
||||
|
||||
### **Quality Metrics**
|
||||
|
||||
- **Readability scores**: Measure content clarity
|
||||
- **User satisfaction**: Survey-based quality assessment
|
||||
- **Task completion**: Success rate of documented procedures
|
||||
- **Support reduction**: Decrease in help requests
|
||||
- **Knowledge retention**: Long-term user understanding
|
||||
|
||||
---
|
||||
|
||||
**See also**:
|
||||
|
||||
- `.cursor/rules/docs/markdown_core.mdc` for core formatting standards
|
||||
- `.cursor/rules/docs/markdown_templates.mdc` for document templates
|
||||
- `.cursor/rules/docs/markdown_workflow.mdc` for validation workflows
|
||||
- `.cursor/rules/docs/meta_rule_usage_guide.md` for how to use meta-rules
|
||||
- `.cursor/rules/core/base_context.mdc` for human competence principles
|
||||
|
||||
**Status**: Active documentation meta-rule
|
||||
**Priority**: High
|
||||
**Estimated Effort**: Ongoing reference
|
||||
**Dependencies**: All bundled sub-rules
|
||||
**Stakeholders**: Documentation team, Development team, Users
|
||||
Reference in New Issue
Block a user