diff --git a/docs/standards/task-documentation-standard.md b/docs/standards/task-documentation-standard.md new file mode 100644 index 0000000..dc1f18a --- /dev/null +++ b/docs/standards/task-documentation-standard.md @@ -0,0 +1,806 @@ +# Task Documentation Standard +## Firefrost Gaming Operations Manual + +**Document Status:** ACTIVE STANDARD +**Created:** February 16, 2026 +**Created By:** The Chronicler (current session) +**Authority:** Michael "Frostystyle" Krause + The Chronicler +**Version:** 1.0 +**Applies To:** All tasks in `docs/core/tasks.md` + +--- + +## 🎯 PURPOSE + +### The Problem This Solves + +**Before this standard:** +- Tasks.md became a 1000+ line mixed-detail document +- Implementation details buried in master task list +- Hard to find related documentation +- Duplication across multiple files +- Updates in one place didn't propagate +- "Which version is authoritative?" confusion +- Context muddying (high-level mixed with low-level) + +**After this standard:** +- Tasks.md stays high-level (executive summary) +- Each task gets its own directory for all related docs +- Clear separation: planning vs implementation vs operations +- Single source of truth per topic +- Easy to find everything related to a task +- Scalable (task can have 1 or 20 documents) + +--- + +## 📁 DIRECTORY STRUCTURE + +### Standard Layout + +``` +docs/ +├── core/ +│ └── tasks.md # Master task list (high-level only) +│ +├── tasks/ # One directory per major task +│ ├── [task-name]/ +│ │ ├── README.md # Task overview (required) +│ │ ├── deployment-plan.md # How to deploy/build (if applicable) +│ │ ├── usage-guide.md # How to use after deployed +│ │ ├── troubleshooting.md # Common issues and solutions +│ │ ├── maintenance.md # Ongoing operations +│ │ ├── prerequisites.md # What's needed before starting +│ │ ├── testing-checklist.md # Validation steps +│ │ ├── config-examples/ # Sample configurations +│ │ ├── scripts/ # Any automation scripts +│ │ └── archive/ # Historical versions +│ │ +│ ├── whitelist-manager/ +│ │ ├── README.md +│ │ ├── deployment-plan.md +│ │ ├── usage-guide.md +│ │ └── troubleshooting.md +│ │ +│ ├── frostwall-protocol/ +│ │ ├── README.md +│ │ ├── deployment-plan.md +│ │ ├── gre-tunnel-config.md +│ │ ├── ufw-rules.md +│ │ └── recovery-procedures.md +│ │ +│ └── mailcow-email/ +│ ├── README.md +│ ├── deployment-plan.md +│ ├── dns-configuration.md +│ └── ssl-setup.md +``` + +--- + +## 📝 TASK DIRECTORY REQUIREMENTS + +### Required Files (Every Task) + +**1. README.md** +- Task overview and purpose +- Quick reference links to other docs in directory +- Status (planning, in-progress, deployed, deprecated) +- Owner/responsibility +- Last updated date + +**Example:** +```markdown +# Whitelist Manager Web Dashboard + +**Status:** Planning +**Owner:** Michael "Frostystyle" Krause +**Priority:** Tier 0 - Immediate Win +**Last Updated:** 2026-02-16 + +## Quick Links +- [Deployment Plan](deployment-plan.md) - Full build guide +- [Usage Guide](usage-guide.md) - How to use +- [Troubleshooting](troubleshooting.md) - Common issues + +## Overview +Web dashboard for managing Minecraft server whitelists... + +## Documentation in This Directory +- `deployment-plan.md` - Complete 6-phase deployment +- `usage-guide.md` - Staff usage instructions +- `troubleshooting.md` - Error recovery +``` + +### Optional Files (As Needed) + +**deployment-plan.md** - For infrastructure/build tasks +- Complete step-by-step deployment +- Prerequisites checklist +- Phase breakdown with time estimates +- Code examples +- Testing procedures +- Rollback procedures + +**usage-guide.md** - For tools/services after deployment +- How staff use the tool +- Common workflows +- Screenshots/examples +- Access control + +**troubleshooting.md** - For operational tasks +- Common issues +- Error messages and solutions +- Recovery procedures +- Emergency contacts + +**maintenance.md** - For ongoing operations +- Daily/weekly/monthly tasks +- Update procedures +- Backup procedures +- Health checks + +**prerequisites.md** - For complex deployments +- Required access/credentials +- Dependencies +- System requirements +- Pre-flight checklist + +**testing-checklist.md** - For quality assurance +- Test scenarios +- Validation steps +- Success criteria +- Regression tests + +--- + +## 📋 TASKS.MD FORMAT + +### High-Level Entry Only + +**What belongs in tasks.md:** +- ✅ Task number and name +- ✅ Time estimate +- ✅ Priority/tier +- ✅ Status (ready/blocked/in-progress/complete) +- ✅ **Reference to task directory** +- ✅ 2-3 sentence overview +- ✅ Key deliverables (bullet points) +- ✅ Dependencies (what blocks this) +- ✅ Quick summary of value/outcome + +**What does NOT belong in tasks.md:** +- ❌ Step-by-step instructions +- ❌ Code examples +- ❌ Configuration details +- ❌ Troubleshooting guides +- ❌ Full deployment procedures +- ❌ Anything longer than 1 screen + +### Template + +```markdown +### [#]. [Task Name] +**Time:** [X hours] +**Status:** [READY/BLOCKED/IN-PROGRESS/COMPLETE] +**Priority:** [Tier X - Description] +**Documentation:** `docs/tasks/[task-name]/` + +**Overview:** +[2-3 sentence description of what this task accomplishes] + +**Key Deliverables:** +- [Deliverable 1] +- [Deliverable 2] +- [Deliverable 3] + +**Dependencies:** +- Blocks: [Tasks that need this done first] +- Blocked by: [Tasks that must complete before this] + +**Value:** +[One sentence on why this matters] + +**Quick Reference:** +- `README.md` - Task overview +- `deployment-plan.md` - Build guide +- `usage-guide.md` - How to use + +**See task directory for complete documentation.** +``` + +--- + +## 🔄 WORKFLOW + +### Creating a New Task + +**Step 1: Add to tasks.md** +```bash +# Add high-level entry in tasks.md following template above +``` + +**Step 2: Create task directory** +```bash +mkdir -p docs/tasks/[task-name] +cd docs/tasks/[task-name] +``` + +**Step 3: Create README.md** +```bash +# Use README template (see above) +# Include quick links, overview, doc list +``` + +**Step 4: Create supporting docs as needed** +```bash +# deployment-plan.md (if building something) +# usage-guide.md (if creating a tool) +# troubleshooting.md (if operational complexity) +# etc. +``` + +**Step 5: Commit to Git** +```bash +git add docs/tasks/[task-name]/ +git commit -m "Add [task-name] documentation" +git push +``` + +### Updating an Existing Task + +**Update in task directory:** +```bash +cd docs/tasks/[task-name] +# Edit relevant .md files +git commit -m "Update [task-name]: [what changed]" +``` + +**Update tasks.md only if:** +- Status changes (ready → in-progress → complete) +- Time estimate significantly changes +- Priority/tier changes +- High-level scope changes + +**DO NOT update tasks.md for:** +- Implementation detail changes +- New troubleshooting steps +- Updated configurations +- Minor clarifications + +### Completing a Task + +**Step 1: Mark complete in task directory** +```bash +# Update README.md status to "DEPLOYED" or "COMPLETE" +# Add completion date +# Add "completed by" attribution +``` + +**Step 2: Update tasks.md** +```markdown +### [#]. [Task Name] — ✅ COMPLETE +**Completed:** [Date] +**Completed By:** [Person/Chronicler] +**Documentation:** `docs/tasks/[task-name]/` + +[Brief summary of outcome] + +**See task directory for complete documentation.** +``` + +**Step 3: Move to completed section** +```markdown +## ✅ COMPLETED TASKS + +### [Task Name] +[Keep the completed entry for reference] +``` + +--- + +## 📚 NAMING CONVENTIONS + +### Directory Names +- **Format:** `[descriptive-name]` (lowercase, hyphens) +- **Examples:** + - `whitelist-manager` + - `frostwall-protocol` + - `mailcow-email` + - `ai-stack-deployment` + - `terraria-branding-training` + +### File Names +- **Format:** `[purpose].md` (lowercase, hyphens) +- **Standard names:** + - `README.md` (always capitalized) + - `deployment-plan.md` + - `usage-guide.md` + - `troubleshooting.md` + - `maintenance.md` + - `prerequisites.md` + - `testing-checklist.md` + +### Avoid +- ❌ Spaces in names +- ❌ Special characters +- ❌ ALL_CAPS (except README.md) +- ❌ Version numbers in filenames (use Git history) +- ❌ Dates in filenames (use Git history) + +--- + +## 🎨 DOCUMENT FORMATTING + +### Standard Header (All Task Docs) + +```markdown +# [Document Title] + +**Task:** [Task Name] +**Document Type:** [deployment-plan/usage-guide/troubleshooting/etc] +**Status:** [DRAFT/ACTIVE/DEPRECATED] +**Last Updated:** [YYYY-MM-DD] +**Owner:** [Person responsible] + +--- + +[Document content...] +``` + +### Section Hierarchy +```markdown +# Top-level heading (document title) +## Major sections +### Sub-sections +#### Details (use sparingly) +``` + +### Code Blocks +```markdown +# Always specify language +```bash +# Good +command --flag value +``` + +# Not this +``` +command --flag value +``` +``` + +### File Paths +```markdown +# Use backticks for paths +Configuration file: `docs/tasks/example/config.json` + +# Use code blocks for file contents +**File:** `config.json` +```json +{ + "key": "value" +} +``` +``` + +--- + +## ✅ MIGRATION STRATEGY + +### For Existing Tasks + +**Phase 1: New Standard (Now)** +- ✅ Document created +- ✅ Standard established +- ✅ All new tasks follow this pattern + +**Phase 2: Gradual Migration (Ongoing)** +- When touching an existing task, migrate its docs +- No rush, no breaking changes +- Natural evolution over time + +**Phase 3: Complete Migration (Future)** +- All tasks have dedicated directories +- Tasks.md is purely high-level +- Complete consistency + +### Migration Checklist (Per Task) + +When migrating an existing task: + +- [ ] Create `docs/tasks/[task-name]/` directory +- [ ] Create `README.md` in task directory +- [ ] Move/create relevant docs: + - [ ] deployment-plan.md (if exists) + - [ ] usage-guide.md (if needed) + - [ ] troubleshooting.md (if needed) +- [ ] Update tasks.md to reference new directory +- [ ] Update any links in other docs +- [ ] Test all links work +- [ ] Commit changes +- [ ] Delete old scattered docs (after confirming migration complete) + +--- + +## 🔍 EXAMPLES + +### Example 1: Simple Task (Command Center Cleanup) + +**Directory:** +``` +docs/tasks/command-center-cleanup/ +├── README.md # Overview +└── procedure.md # Step-by-step cleanup +``` + +**tasks.md entry:** +```markdown +### 2. Command Center Root Cleanup +**Time:** 15 minutes +**Status:** READY +**Documentation:** `docs/tasks/command-center-cleanup/` + +**Overview:** Housekeeping - move Gitea backups, archive logs, delete cruft. + +**See task directory for cleanup procedure.** +``` + +--- + +### Example 2: Complex Infrastructure Task (Frostwall) + +**Directory:** +``` +docs/tasks/frostwall-protocol/ +├── README.md # Overview +├── deployment-plan.md # Full deployment +├── gre-tunnel-configuration.md # GRE setup +├── nat-dmz-configuration.md # NAT/DMZ setup +├── ufw-rules.md # Firewall rules +├── ip-hierarchy.md # IP allocation +├── testing-checklist.md # Validation +├── troubleshooting.md # Recovery +├── maintenance.md # Ongoing ops +└── config-examples/ + ├── gre-tunnel-tx1.conf + ├── gre-tunnel-nc1.conf + └── ufw-rules-example.sh +``` + +**tasks.md entry:** +```markdown +### 5. The Frostwall Protocol — GRE Tunnel Security +**Time:** 3-4 hours +**Status:** READY +**Priority:** CRITICAL +**Documentation:** `docs/tasks/frostwall-protocol/` + +**Overview:** DDoS protection using GRE tunnels from Command Center to remote nodes. Hides real server IPs, protects all game traffic. + +**Key Deliverables:** +- GRE tunnels: Command Center ↔ TX1, NC1 +- 1-to-1 NAT/DMZ with /29 IP block +- Iron Wall UFW rules +- Self-healing persistence + +**Dependencies:** +- Blocks: Mailcow, AI Stack, all Tier 2+ work +- Blocked by: None (foundational) + +**Quick Reference:** +- `deployment-plan.md` - Complete build guide +- `gre-tunnel-configuration.md` - Tunnel setup +- `troubleshooting.md` - Recovery procedures + +**See task directory for complete documentation.** +``` + +--- + +### Example 3: Service Deployment (Whitelist Manager) + +**Directory:** +``` +docs/tasks/whitelist-manager/ +├── README.md # Overview +├── deployment-plan.md # 6-phase deployment +├── prerequisites.md # What's needed +├── usage-guide.md # How staff use it +├── troubleshooting.md # Common issues +├── maintenance.md # Ongoing ops +└── config-examples/ + ├── config.json.example + └── nginx-example.conf +``` + +**tasks.md entry:** +```markdown +### 1. Centralized Whitelist Manager Web Dashboard +**Time:** 2-2.5 hours +**Status:** READY TO BUILD +**Documentation:** `docs/tasks/whitelist-manager/` + +**Overview:** Build web dashboard at whitelist.firefrostgaming.com to manage player whitelists across 11 Minecraft servers. + +**Key Deliverables:** +- Web interface with server list +- Toggle whitelist ON/OFF per server +- Add/remove players (individual or bulk) +- Staff authentication + +**Value:** 15-minute manual task → 30 seconds + +**Quick Reference:** +- `deployment-plan.md` - Complete 6-phase guide +- `prerequisites.md` - API keys, credentials needed +- `usage-guide.md` - How to use after deployed + +**See task directory for complete documentation.** +``` + +--- + +## 🚀 BENEFITS + +### For Task Execution +- ✅ All related docs in one place +- ✅ Clear what exists vs what's missing +- ✅ Easy to find "how do I...?" +- ✅ Self-contained (task directory is portable) + +### For Maintenance +- ✅ Update one place, not scattered files +- ✅ Version control per task directory +- ✅ Easy to deprecate old approaches +- ✅ Clear documentation audit trail + +### For Collaboration +- ✅ New Chroniclers know where to look +- ✅ Staff can find usage guides +- ✅ Meg can reference without digging +- ✅ Future children see complete context + +### For Scaling +- ✅ Task can grow from 1 to 20 docs without cluttering +- ✅ Tasks.md stays readable as we hit 50+ tasks +- ✅ Easy to archive completed task directories +- ✅ Pattern proven, repeatable + +--- + +## 📏 QUALITY STANDARDS + +### Documentation Must Be: + +**1. Discoverable** +- Task directory name is obvious +- README.md provides clear navigation +- Links work and are maintained + +**2. Complete** +- All promised docs exist +- No "TODO" placeholders older than 1 week +- Every procedure has success criteria + +**3. Tested** +- Procedures verified before documenting +- Code examples actually work +- Links confirmed valid + +**4. Maintained** +- Last updated date is accurate +- Deprecated docs marked clearly +- Changes propagate to dependent docs + +**5. Accessible** +- Written for The Chronicler AND staff +- Technical jargon explained +- Assumes reader hasn't seen other docs + +### Review Checklist + +Before marking task docs complete: + +- [ ] README.md exists and is current +- [ ] All referenced docs exist +- [ ] All links work +- [ ] Code examples tested +- [ ] Procedures include success criteria +- [ ] Screenshots/diagrams added if helpful +- [ ] Last updated date is current +- [ ] Committed to Git +- [ ] Referenced correctly in tasks.md + +--- + +## 🔄 DOCUMENT LIFECYCLE + +### States + +**DRAFT** - Being written, not yet ready for use +**ACTIVE** - Current, tested, use this version +**DEPRECATED** - Old approach, kept for reference +**ARCHIVED** - Historical, moved to archive/ subdirectory + +### Transitions + +``` +DRAFT → ACTIVE + When: Tested and verified + Action: Update status header + +ACTIVE → DEPRECATED + When: Better approach exists + Action: Add deprecation notice, link to new doc + +DEPRECATED → ARCHIVED + When: No longer referenced + Action: Move to archive/ subdirectory +``` + +### Deprecation Notice Template + +```markdown +# [Document Title] + +> ⚠️ **DEPRECATED:** This document describes an old approach. +> +> **New approach:** See [new-approach.md](new-approach.md) +> **Deprecated on:** 2026-03-15 +> **Reason:** [Why this was replaced] +> +> This document is kept for historical reference only. + +--- + +[Original content preserved below...] +``` + +--- + +## 💡 TIPS & BEST PRACTICES + +### Writing Task Documentation + +**Start with README.md** +- Gives you structure +- Identifies what docs you need +- Prevents scope creep + +**One purpose per document** +- deployment-plan.md ≠ usage-guide.md +- Keep concerns separated +- Easier to maintain + +**Code examples over prose** +```bash +# Good: Show the actual command +curl -X POST https://api.example.com/endpoint + +# Not this: "Use curl to POST to the API endpoint" +``` + +**Test everything you document** +- Run every command +- Follow every procedure +- Verify every link +- Screenshot actual results + +**Write for your future self** +- You'll forget details +- Document why, not just what +- Include context for decisions +- Link to related discussions + +### Organizing Complex Tasks + +**Use subdirectories for categories:** +``` +docs/tasks/frostwall-protocol/ +├── README.md +├── planning/ +│ ├── architecture-decisions.md +│ └── ip-allocation-plan.md +├── deployment/ +│ ├── phase-1-gre-tunnels.md +│ ├── phase-2-nat-config.md +│ └── phase-3-ufw-rules.md +└── operations/ + ├── monitoring.md + └── incident-response.md +``` + +**Break long procedures into phases:** +- Phase 1: Prerequisites +- Phase 2: Core deployment +- Phase 3: Testing +- Phase 4: Monitoring + +**Link between related docs:** +```markdown +See also: +- [GRE Tunnel Config](gre-tunnel-configuration.md) +- [UFW Rules](ufw-rules.md) +- [Troubleshooting](troubleshooting.md) +``` + +--- + +## 🎯 ENFORCEMENT + +### This Standard Applies To: + +✅ **All new tasks** added to tasks.md +✅ **All major updates** to existing tasks +✅ **All infrastructure deployments** +✅ **All service configurations** +✅ **All operational procedures** + +### Exceptions: + +**Quick wins (<30 min)** can be inline in tasks.md if: +- Single document would be complete reference +- No ongoing maintenance needed +- Unlikely to expand in scope + +**Example:** Command Center Cleanup might stay inline, or get minimal directory. + +### Responsible Parties: + +**The Chronicler:** +- Maintains this standard +- Creates task directories for new work +- Migrates existing tasks when touched +- Reviews documentation quality + +**Michael:** +- Approves deviations from standard +- Provides feedback on clarity +- Tests procedures before deployment + +**Meg:** +- Reviews usage guides for staff tools +- Confirms documentation is accessible + +--- + +## 📋 CHANGELOG + +### Version 1.0 (2026-02-16) +- Initial standard created +- Established directory structure +- Defined file requirements +- Created templates and examples +- Set quality standards +- Documented migration strategy + +**Created by:** The Chronicler (current session) +**Approved by:** Michael "Frostystyle" Krause (implicit via Option B selection) + +--- + +## 🔗 REFERENCES + +### Related Standards +- `docs/standards/git-workflow.md` (if exists) +- `docs/standards/naming-conventions.md` (if exists) +- `docs/standards/code-style.md` (if exists) + +### Example Task Directories +- `docs/tasks/whitelist-manager/` - First task using this standard +- `docs/tasks/frostwall-protocol/` - Complex infrastructure example (when created) +- `docs/tasks/mailcow-email/` - Service deployment example (when created) + +### Core Documents +- `docs/core/tasks.md` - Master task list +- `DOCUMENT-INDEX.md` - Repository file map +- `README.md` - Repository overview + +--- + +**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️ + +**Standard Status:** ACTIVE +**Applies From:** February 16, 2026 +**Review Cycle:** Quarterly or as needed +**Maintained By:** The Chronicler lineage