forked from trent_larson/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:
@@ -2,6 +2,9 @@
|
||||
|
||||
> **Agent role**: Reference this file for document templates, structure,
|
||||
> and examples when creating new documentation.
|
||||
>
|
||||
> **Focus**: Create educational content that increases human competence,
|
||||
> not just technical descriptions.
|
||||
|
||||
## Document Templates
|
||||
|
||||
@@ -18,10 +21,16 @@
|
||||
|
||||
Brief description of the document's purpose and scope.
|
||||
|
||||
**Educational Goal**: What will the reader learn and how will it increase
|
||||
their competence?
|
||||
|
||||
## Current State
|
||||
|
||||
Description of current situation or problem.
|
||||
|
||||
**Why This Matters**: Explain the business value and user benefit of
|
||||
addressing this situation.
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
### Phase 1: Foundation
|
||||
@@ -29,12 +38,18 @@ Description of current situation or problem.
|
||||
- [ ] Task 1
|
||||
- [ ] Task 2
|
||||
|
||||
**Learning Context**: What concepts should the reader understand before
|
||||
proceeding with implementation?
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Review and approve plan**
|
||||
2. **Begin implementation**
|
||||
3. **Test and validate**
|
||||
|
||||
**Continued Learning**: Where can the reader go next to deepen their
|
||||
understanding?
|
||||
|
||||
---
|
||||
|
||||
**Status**: Ready for implementation
|
||||
@@ -57,6 +72,9 @@ Description of current situation or problem.
|
||||
|
||||
Brief description of the technical specification.
|
||||
|
||||
**Business Context**: Why is this specification needed and what problem
|
||||
does it solve for users?
|
||||
|
||||
## Requirements
|
||||
|
||||
### Functional Requirements
|
||||
@@ -75,6 +93,9 @@ Brief description of the technical specification.
|
||||
|
||||
Description of the technical architecture.
|
||||
|
||||
**Design Rationale**: Why was this architecture chosen over alternatives?
|
||||
What are the trade-offs and benefits?
|
||||
|
||||
### Data Models
|
||||
|
||||
```typescript
|
||||
@@ -98,6 +119,79 @@ interface APIResponse<T> {
|
||||
## Testing Strategy
|
||||
|
||||
- [ ] Unit tests
|
||||
|
||||
**Learning from Testing**: What insights does testing provide about the
|
||||
system's behavior and design?
|
||||
|
||||
---
|
||||
|
||||
## Educational Documentation Template
|
||||
|
||||
### **Concept Explanation Template**
|
||||
|
||||
```markdown
|
||||
## What is [Concept Name]?
|
||||
|
||||
Brief, clear definition of the concept.
|
||||
|
||||
## Why Does [Concept Name] Matter?
|
||||
|
||||
Explain the business value and user benefit.
|
||||
|
||||
## How Does [Concept Name] Work?
|
||||
|
||||
High-level explanation of the mechanism.
|
||||
|
||||
## When Would You Use [Concept Name]?
|
||||
|
||||
Real-world scenarios and use cases.
|
||||
|
||||
## Common Misconceptions
|
||||
|
||||
Address typical misunderstandings.
|
||||
|
||||
## Examples
|
||||
|
||||
Concrete examples that illustrate the concept.
|
||||
|
||||
## Next Steps
|
||||
|
||||
Where to learn more about related concepts.
|
||||
```
|
||||
|
||||
### **Tutorial Template**
|
||||
|
||||
```markdown
|
||||
## Learning Objective
|
||||
|
||||
What the reader will accomplish by the end.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
What the reader should know before starting.
|
||||
|
||||
## Step-by-Step Guide
|
||||
|
||||
1. **Step 1**: What to do and why
|
||||
2. **Step 2**: What to do and why
|
||||
3. **Step 3**: What to do and why
|
||||
|
||||
## Verification
|
||||
|
||||
How to confirm the tutorial was successful.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Common issues and how to resolve them.
|
||||
|
||||
## What You've Learned
|
||||
|
||||
Summary of key concepts and skills.
|
||||
|
||||
## Next Steps
|
||||
|
||||
Where to apply this knowledge next.
|
||||
```
|
||||
- [ ] Integration tests
|
||||
- [ ] E2E tests
|
||||
|
||||
@@ -209,6 +303,7 @@ Standard implementation plans follow Phase 1 (Foundation), Phase 2
|
||||
|
||||
**See also**:
|
||||
|
||||
- `.cursor/rules/meta_documentation.mdc` for comprehensive documentation workflow
|
||||
- `.cursor/rules/docs/markdown_core.mdc` for core formatting standards
|
||||
- `.cursor/rules/docs/markdown_workflow.mdc` for validation workflows
|
||||
|
||||
|
||||
Reference in New Issue
Block a user