daily-notification-plugin/.cursor/rules/docs/documentation.mdc

# Documentation Generation — Human Competence First

**Author**: Matthew Raymer
**Date**: 2025-08-17
**Status**: 🎯 **ACTIVE** - Core Documentation Standards

## Overview

This guide establishes **how documentation should be created and maintained**
across all projects, emphasizing **human competence building** and
**collaborative learning** while ensuring technical accuracy and maintainability.

## Core Principles (Human Competence First)

### 1. **Learning Over Information Dumping**

- **Educational value**: Documents must clearly explain system workings
- **Progressive complexity**: Start simple, build to advanced concepts
- **Real-world examples**: Include practical, actionable examples
- **Why it matters**: Understanding the "why" builds deeper competence

### 2. **Collaboration Over Isolation**

- **Team review**: Documentation should invite discussion and iteration
- **Shared ownership**: Multiple perspectives improve quality and accuracy
- **Feedback loops**: Regular review cycles keep content relevant
- **Why it matters**: Collaborative documentation builds team knowledge

### 3. **Maintainability Over Completeness**

- **Small, focused sets**: Prefer depth over breadth
- **Worth preserving**: Content must motivate humans to keep it updated
- **Clear ownership**: Designate maintainers for each document
- **Why it matters**: Maintainable docs stay useful over time

### 4. **Quality Over Quantity**

- **Avoid filler**: No shallow, generic, or AI-generated explanations
- **Clarity first**: Complex concepts explained simply
- **Actionable content**: Readers should know what to do next
- **Why it matters**: Quality content builds trust and competence

## Documentation Standards

### Content Structure

#### Document Header (Required)

```markdown
# Document Title

**Author**: [Name]
**Date**: YYYY-MM-DD
**Status**: 🎯 **STATUS** - Brief description
**Maintainer**: [Name]

## Overview

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

#### Section Organization

1. **Overview/Introduction** - Purpose and scope
2. **Current State** - What exists now
3. **Implementation Details** - How things work
4. **Examples** - Real-world usage
5. **Next Steps** - What to do next
6. **References** - Related resources

### Writing Guidelines

#### **For LLMs (Required)**

- **Always start with purpose**: Why does this document exist?
- **Include learning objectives**: What will readers understand after reading?
- **Provide examples**: Show, don't just tell
- **End with action**: What should readers do next?

#### **For Human Writers**

- **Write for your future self**: Will you understand this in 6 months?
- **Consider skill levels**: Different readers have different needs
- **Include context**: Why does this matter for the project?
- **Invite feedback**: How can this be improved?

## Documentation Types

### 1. **Technical Guides**

- **Purpose**: Explain how systems work
- **Audience**: Developers, engineers, technical users
- **Focus**: Implementation details, APIs, configurations
- **Examples**: Code snippets, configuration files, diagrams

### 2. **Process Documentation**

- **Purpose**: Explain how to accomplish tasks
- **Audience**: Team members, stakeholders
- **Focus**: Step-by-step procedures, workflows
- **Examples**: Checklists, flowcharts, decision trees

### 3. **Architecture Documents**

- **Purpose**: Explain system design and structure
- **Audience**: Architects, developers, stakeholders
- **Focus**: High-level design, trade-offs, decisions
- **Examples**: System diagrams, ADRs, design patterns

### 4. **User Guides**

- **Purpose**: Help users accomplish goals
- **Audience**: End users, customers
- **Focus**: User workflows, features, troubleshooting
- **Examples**: Screenshots, step-by-step instructions

## Quality Assurance

### **Before Publishing Documentation**

- [ ] **Purpose clear**: Why does this document exist?
- [ ] **Audience defined**: Who is this written for?
- [ ] **Examples included**: Are there practical examples?
- [ ] **Actionable**: Do readers know what to do next?
- [ ] **Maintainable**: Is it easy to keep updated?
- [ ] **Collaborative**: Does it invite team input?

### **After Publishing Documentation**

- [ ] **Feedback collected**: Have team members reviewed it?
- [ ] **Usage tracked**: Are people actually using it?
- [ ] **Updates planned**: When will it be reviewed next?
- [ ] **Ownership clear**: Who maintains this document?

## Implementation Examples

### Good Documentation Example

```markdown
# User Authentication System

**Author**: Matthew Raymer
**Date**: 2025-08-17
**Status**: 🎯 **ACTIVE** - Production System
**Maintainer**: Security Team

## Overview

This document explains how user authentication works in our system,
including login flows, security measures, and troubleshooting steps.

## Learning Objectives

After reading this document, you will understand:
- How users log in and authenticate
- What security measures protect user accounts
- How to troubleshoot common authentication issues
- When to escalate security concerns

## Current Implementation

### Login Flow

1. User enters credentials
2. System validates against database
3. JWT token generated and returned
4. Token stored in secure cookie

### Security Measures

- Password hashing with bcrypt
- Rate limiting on login attempts
- JWT expiration after 24 hours
- HTTPS enforcement for all auth requests

## Examples

### Login Request

```json
POST /api/auth/login
{
  "email": "user@example.com",
  "password": "securepassword123"
}
```

### Successful Response

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires": "2025-08-18T12:00:00Z"
}
```

## Troubleshooting

### Common Issues

- **Invalid credentials**: Check email/password combination
- **Token expired**: User needs to log in again
- **Rate limited**: Wait 15 minutes before retrying

### Escalation Path

1. Check system logs for errors
2. Verify database connectivity
3. Contact security team if suspicious activity

## Next Steps

1. **Test the system**: Try logging in with test credentials
2. **Review security**: Ensure your implementation follows these patterns
3. **Document issues**: Add new troubleshooting steps as you discover them

## References

- [JWT Documentation](https://jwt.io/)
- [Security Best Practices](./security-guide.md)
- [API Reference](./api-docs.md)

---

**Last Updated**: 2025-08-17
**Next Review**: 2025-09-17
**Stakeholders**: Development Team, Security Team, Product Team

### Bad Documentation Example

```markdown
# Authentication

This document describes the authentication system.

## Overview

The system has authentication.

## Implementation

Users can log in.

## Conclusion

That's how authentication works.
```

## Collaboration Points

### **Code Reviews**

- Include documentation updates in code review process
- Ensure new features have corresponding documentation
- Validate that examples match actual implementation

### **Team Reviews**

- Schedule regular documentation review sessions
- Invite different team members to review content
- Collect feedback on clarity and usefulness

### **User Testing**

- Have actual users try to follow documentation
- Observe where they get stuck or confused
- Update content based on real usage patterns

## Maintenance Schedule

### **Weekly**

- Review documentation usage metrics
- Collect feedback from team members
- Plan updates for outdated content

### **Monthly**

- Full review of high-priority documents
- Update examples and screenshots
- Validate links and references

### **Quarterly**

- Comprehensive review of all documentation
- Identify gaps and opportunities
- Plan major documentation projects

## Success Metrics

### **Usage Metrics**

- **Document views**: How often is content accessed?
- **Time on page**: How long do readers spend?
- **Search queries**: What are people looking for?

### **Quality Metrics**

- **Feedback scores**: How do readers rate content?
- **Update frequency**: How often is content refreshed?
- **Maintainer satisfaction**: Are maintainers happy with their docs?

### **Competence Metrics**

- **Question reduction**: Fewer basic questions from team?
- **Implementation speed**: Faster feature development?
- **Knowledge transfer**: Better onboarding for new team members?

## Tools and Resources

### **Documentation Platforms**

- **Markdown**: Standard format for technical documentation
- **GitBook**: Collaborative documentation hosting
- **Notion**: Team knowledge management
- **Confluence**: Enterprise documentation platform

### **Quality Tools**

- **Markdown linting**: Ensure consistent formatting
- **Link checking**: Validate references and links
- **Spell checking**: Maintain professional appearance
- **Accessibility**: Ensure content is usable by all

### **Collaboration Tools**

- **Version control**: Track changes and history
- **Review systems**: Collect feedback and approvals
- **Analytics**: Understand usage patterns
- **Notifications**: Keep team informed of updates

## Implementation Next Steps

1. **Review existing documentation**: Apply these principles to current docs
2. **Identify gaps**: What documentation is missing or outdated?
3. **Plan improvements**: Prioritize documentation updates
4. **Establish processes**: Set up regular review and update cycles

---

**Last Updated**: 2025-08-17
**Version**: 2.0
**Maintainer**: Matthew Raymer
**Stakeholders**: All Teams
**Next Review**: 2025-09-17