# 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