From 2eaff5b79fed364d5eba5eb38e4b7bf76326884d Mon Sep 17 00:00:00 2001 From: DanConwayDev Date: Wed, 3 Dec 2025 11:19:40 +0000 Subject: remove docs archive --- docs/archive/2025-11-04-diataxis-complete.md | 280 --------------------------- 1 file changed, 280 deletions(-) delete mode 100644 docs/archive/2025-11-04-diataxis-complete.md (limited to 'docs/archive/2025-11-04-diataxis-complete.md') diff --git a/docs/archive/2025-11-04-diataxis-complete.md b/docs/archive/2025-11-04-diataxis-complete.md deleted file mode 100644 index a2d0a42..0000000 --- a/docs/archive/2025-11-04-diataxis-complete.md +++ /dev/null @@ -1,280 +0,0 @@ -# ✅ Diátaxis Migration Complete - -**Date:** November 4, 2025 -**Framework:** [Diátaxis](https://diataxis.fr/) -**Status:** Complete and enforced - ---- - -## What We Did - -Migrated all ngit-grasp documentation to the **Diátaxis framework**, organizing content into four clear categories based on purpose and audience. - ---- - -## The Diátaxis Framework - -``` - PRACTICAL THEORETICAL - ───────── ─────────── - -LEARNING │ Tutorials │ Explanation │ - │ │ │ -WORKING │ How-To │ Reference │ - │ Guides │ │ -``` - -**Four questions, four categories:** -- "Can you teach me to...?" → **Tutorial** -- "How do I...?" → **How-To Guide** -- "What is...?" → **Reference** -- "Why...?" → **Explanation** - ---- - -## Documentation Structure - -``` -docs/ -├── README.md # Main navigation -│ -├── tutorials/ # 📚 Learning-oriented -│ ├── getting-started.md # ✅ First-time setup -│ └── first-audit.md # ✅ Learn grasp-audit -│ -├── how-to/ # 🔧 Task-oriented -│ └── nix-flakes.md # ✅ Nix environment -│ -├── reference/ # 📖 Information-oriented -│ ├── configuration.md # ✅ Config options -│ ├── git-protocol.md # ✅ Git Smart HTTP -│ └── test-strategy.md # ✅ Testing approach -│ -├── explanation/ # 💡 Understanding-oriented -│ ├── architecture.md # ✅ System design -│ ├── inline-authorization.md # ✅ Key decision -│ ├── comparison.md # ✅ vs ngit-relay -│ └── decisions.md # ✅ Design choices -│ -├── archive/ # Historical -└── learnings/ # DEPRECATED -``` - ---- - -## Files Created - -### New Documentation (7 files) -1. `docs/README.md` - Main navigation with Diátaxis diagram -2. `tutorials/first-audit.md` - New tutorial for grasp-audit -3. `how-to/nix-flakes.md` - Migrated from learnings/ -4. `reference/configuration.md` - Complete config reference -5. `explanation/inline-authorization.md` - Deep dive on key decision -6. `DIATAXIS_MIGRATION.md` - Migration documentation -7. `DIATAXIS_MIGRATION_VISUAL.txt` - Visual summary - -### Category Guides (4 files) -1. `tutorials/README.md` - Tutorial category guide -2. `how-to/README.md` - How-to category guide -3. `reference/README.md` - Reference category guide -4. `explanation/README.md` - Explanation category guide - -### Deprecation Notices (1 file) -1. `learnings/README.md` - Migration notice - ---- - -## Files Migrated - -### From docs/ to explanation/ -- `ARCHITECTURE.md` → `explanation/architecture.md` -- `COMPARISON.md` → `explanation/comparison.md` -- `DECISION_SUMMARY.md` → `explanation/decisions.md` - -### From docs/ to reference/ -- `GIT_PROTOCOL.md` → `reference/git-protocol.md` -- `TEST_STRATEGY.md` → `reference/test-strategy.md` - -### From learnings/ to how-to/ -- `learnings/nix-flakes.md` → `how-to/nix-flakes.md` - ---- - -## Files Updated - -1. `AGENTS.md` - Added Diátaxis guidelines and enforcement -2. `README.md` - Updated documentation links -3. `docs/README.md` - Complete rewrite with Diátaxis structure - ---- - -## Enforcement - -### AGENTS.md Updates -- ✅ Documentation structure section updated with Diátaxis -- ✅ File lifecycle includes four categories -- ✅ "Before creating documents" includes Diátaxis questions -- ✅ Cleanup process updated -- ✅ `learnings/` marked as deprecated - -### AI Agent Behavior -AI agents will now: -1. Ask Diátaxis questions before creating docs -2. Place content in correct category -3. Follow category-specific guidelines -4. Maintain consistent structure -5. Never create files in `learnings/` - ---- - -## Benefits - -### For Authors -- ✅ Clear guidelines on where to put content -- ✅ Consistent structure across all docs -- ✅ Easy to know what style to use -- ✅ Industry best practice - -### For Readers -- ✅ Know what to expect from each doc -- ✅ Easy to find what you need -- ✅ Can navigate by purpose -- ✅ Better learning experience - -### For Maintainers -- ✅ Easier to review contributions -- ✅ Clearer documentation standards -- ✅ Less duplicate content -- ✅ Sustainable long-term structure - ---- - -## Quick Start for Users - -### New to ngit-grasp? -1. Read [README.md](README.md) -2. Follow [Getting Started Tutorial](docs/tutorials/getting-started.md) -3. Understand [Architecture](docs/explanation/architecture.md) - -### Have a problem to solve? -1. Check [How-To Guides](docs/how-to/) -2. Find your problem -3. Follow the recipe - -### Need technical details? -1. Check [Reference](docs/reference/) -2. Look up what you need -3. Use search or TOC - -### Want to understand design? -1. Read [Explanation](docs/explanation/) -2. Start with [Architecture](docs/explanation/architecture.md) -3. Dive into specific topics - ---- - -## Statistics - -### Documentation Count -- **Tutorials:** 2 (getting-started, first-audit) -- **How-To Guides:** 1 (nix-flakes) + 4 planned -- **Reference:** 3 (configuration, git-protocol, test-strategy) + 3 planned -- **Explanation:** 4 (architecture, inline-authorization, comparison, decisions) -- **Total:** 10 documents + 8 planned - -### Lines of Documentation -- New content: ~2,500 lines -- Migrated content: ~1,500 lines -- Category guides: ~800 lines -- Total: ~4,800 lines of well-organized documentation - ---- - -## Next Steps - -### Immediate -- ✅ Review this summary -- ✅ Archive migration docs to `docs/archive/` -- ✅ Commit all changes - -### Short-term -- 🔜 Complete planned how-to guides (deploy, test-compliance, upgrade-nostr-sdk) -- 🔜 Add GRASP protocol reference -- 🔜 Add API reference when server is implemented - -### Long-term -- 🔜 Generate API docs from code -- 🔜 Add video tutorials -- 🔜 Create interactive examples -- 🔜 Consider translations - ---- - -## Resources - -- **[Diátaxis Framework](https://diataxis.fr/)** - Official documentation -- **[How to Use Diátaxis](https://diataxis.fr/how-to-use-diataxis/)** - Implementation guide -- **[Examples](https://diataxis.fr/examples/)** - Real-world examples -- **[Our Documentation](docs/README.md)** - Main navigation - ---- - -## Verification - -### Structure Check -```bash -cd docs -find tutorials how-to reference explanation -name "*.md" | sort -``` - -**Result:** 14 markdown files in correct structure ✅ - -### Category Distribution -- Tutorials: 2 docs + 1 README -- How-To: 1 doc + 1 README -- Reference: 3 docs + 1 README -- Explanation: 4 docs + 1 README - -**Result:** Balanced distribution ✅ - -### Link Validation -All internal links checked and working ✅ - ---- - -## Success Criteria - -- ✅ All documentation fits into Diátaxis categories -- ✅ Each category has README with guidelines -- ✅ Main navigation uses Diátaxis diagram -- ✅ AGENTS.md enforces Diátaxis -- ✅ Old structure deprecated with migration notices -- ✅ All internal links working -- ✅ Clear reading paths for different users -- ✅ Contributing guidelines updated - -**Result:** All criteria met ✅ - ---- - -## Conclusion - -ngit-grasp documentation now follows the **Diátaxis framework**, providing: - -1. **Clear structure** - Four categories by purpose -2. **Better UX** - Readers know what to expect -3. **Easier maintenance** - Clear guidelines for contributors -4. **Industry standard** - Following best practices -5. **Sustainable** - Scales as project grows - -The migration is **complete** and **enforced** through AGENTS.md. - ---- - -**Completed:** November 4, 2025 -**Framework:** [Diátaxis](https://diataxis.fr/) -**Status:** ✅ Complete and Ready to Use - ---- - -*Archive this file to `docs/archive/2025-11-04-diataxis-migration.md` after review.* -- cgit v1.2.3