crowd-funder-for-time-pwa/.cursor/rules/docs/markdown_templates.mdc

# Markdown Templates & Examples

> **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

### Standard Document Template

```markdown
# Document Title

**Author**: Matthew Raymer
**Date**: YYYY-MM-DD
**Status**: 🎯 **STATUS** - Brief description

## Overview

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

- [ ] 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
**Priority**: Medium
**Estimated Effort**: X days
**Dependencies**: None
**Stakeholders**: Development team
```

### Technical Specification Template

```markdown
# Technical Specification: [Feature Name]

**Author**: Matthew Raymer
**Date**: YYYY-MM-DD
**Status**: 🎯 **DRAFT** - Under Review

## Overview

Brief description of the technical specification.

**Business Context**: Why is this specification needed and what problem
does it solve for users?

## Requirements

### Functional Requirements

- [ ] Requirement 1
- [ ] Requirement 2

### Non-Functional Requirements

- [ ] Performance requirement
- [ ] Security requirement

## Technical Design

### Architecture

Description of the technical architecture.

**Design Rationale**: Why was this architecture chosen over alternatives?
What are the trade-offs and benefits?

### Data Models

```typescript
interface ExampleModel {
  id: string;
  name: string;
  createdAt: Date;
}
```

### API Design

```typescript
interface APIResponse<T> {
  success: boolean;
  data: T;
  error?: string;
}
```

## 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

---

**Status**: Draft
**Priority**: High
**Estimated Effort**: X days
**Dependencies**: None
**Stakeholders**: Development team

```

## Content Examples

### JSON Examples

```json
{
  "property": "value",
  "nested": {
    "property": "value"
  }
}
```

### Shell Commands

```bash
# Command with comment
npm run build:web

# Multi-line command
VITE_GIT_HASH=`git log -1 --pretty=format:%h` \
  vite build --config vite.config.web.mts
```

### TypeScript Examples

```typescript
// Function with JSDoc
const getEnvironmentConfig = (env: string) => {
  switch (env) {
    case 'prod':
      return { /* production settings */ };
    default:
      return { /* development settings */ };
  }
};
```

## File Structure Standards

### Document Header

```markdown
# Document Title

**Author**: Matthew Raymer
**Date**: YYYY-MM-DD
**Status**: 🎯 **STATUS** - Brief description

## Overview

Brief description of the document's purpose and scope.
```

### Section Organization

Standard sections: Overview, Current State, Implementation Plan,
Technical Details, Testing & Validation, Next Steps

## Common Patterns

Standard implementation plans follow Phase 1 (Foundation), Phase 2
(Features), Phase 3 (Testing & Polish) structure.

## Model Implementation Checklist

### Before Using Templates

- [ ] **Template Selection**: Choose appropriate template for document type
- [ ] **Structure Review**: Understand required sections and organization
- [ ] **Content Planning**: Plan what information goes in each section
- [ ] **Audience Analysis**: Ensure template matches target audience needs

### During Template Usage

- [ ] **Section Completion**: Fill in all required sections completely
- [ ] **Example Integration**: Include relevant code examples and patterns
- [ ] **Formatting Consistency**: Apply markdown standards from core rules
- [ ] **Cross-references**: Link to related documentation and resources

### After Template Usage

- [ ] **Content Review**: Verify all sections contain appropriate content
- [ ] **Formatting Check**: Run `npm run markdown:check` for compliance
- [ ] **Template Validation**: Confirm document follows template structure
- [ ] **Quality Assessment**: Ensure content meets project standards

### Template-Specific Requirements

- [ ] **Standard Documents**: Include all required metadata and sections
- [ ] **Technical Specs**: Complete all requirement and design sections
- [ ] **Implementation Plans**: Define clear phases and milestones
- [ ] **Examples**: Provide relevant, working code examples

---

**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

**Status**: Active templates and examples
**Priority**: Medium
**Estimated Effort**: Ongoing reference
**Dependencies**: markdown_core.mdc
**Stakeholders**: Documentation team, Development team