forked from trent_larson/crowd-funder-for-time-pwa
c2aaf3a20d
- 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.
238 lines
8.6 KiB
Plaintext
238 lines
8.6 KiB
Plaintext
# 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
|