crowd-funder-for-time-pwa/.cursor/rules/meta_documentation.mdc

# 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