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-migration.md | 355 -------------------------- 1 file changed, 355 deletions(-) delete mode 100644 docs/archive/2025-11-04-diataxis-migration.md (limited to 'docs/archive/2025-11-04-diataxis-migration.md') diff --git a/docs/archive/2025-11-04-diataxis-migration.md b/docs/archive/2025-11-04-diataxis-migration.md deleted file mode 100644 index deed23d..0000000 --- a/docs/archive/2025-11-04-diataxis-migration.md +++ /dev/null @@ -1,355 +0,0 @@ -# Diátaxis Migration Complete ✅ - -**Date:** November 4, 2025 -**Status:** COMPLETE - ---- - -## What Changed? - -We migrated all documentation to the **[Diátaxis](https://diataxis.fr/) framework**, which organizes content into four clear categories based on purpose and audience. - ---- - -## Before and After - -### Before (Flat Structure) -``` -docs/ -├── ARCHITECTURE.md -├── COMPARISON.md -├── DECISION_SUMMARY.md -├── GETTING_STARTED.md -├── GIT_PROTOCOL.md -├── TEST_STRATEGY.md -├── learnings/ -│ ├── nix-flakes.md -│ ├── nostr-sdk.md -│ └── grasp-audit.md -└── archive/ -``` - -**Problems:** -- Unclear where to put new docs -- Mixed purposes (learning, reference, explanation) -- Hard for readers to know what to expect -- "learnings" was ambiguous - -### After (Diátaxis Structure) -``` -docs/ -├── tutorials/ # Learning-oriented -│ ├── getting-started.md -│ └── first-audit.md -├── how-to/ # Task-oriented -│ └── nix-flakes.md -├── reference/ # Information-oriented -│ ├── configuration.md -│ ├── git-protocol.md -│ └── test-strategy.md -├── explanation/ # Understanding-oriented -│ ├── architecture.md -│ ├── inline-authorization.md -│ ├── comparison.md -│ └── decisions.md -└── archive/ # Historical -``` - -**Benefits:** -- ✅ Clear categorization by purpose -- ✅ Easy to know where to put new docs -- ✅ Readers know what to expect -- ✅ Follows industry best practice - ---- - -## Migration Map - -| Old Location | New Location | Category | -|-------------|-------------|----------| -| `GETTING_STARTED.md` | `tutorials/getting-started.md` | Tutorial | -| *(new)* | `tutorials/first-audit.md` | Tutorial | -| `learnings/nix-flakes.md` | `how-to/nix-flakes.md` | How-To | -| *(planned)* | `how-to/deploy.md` | How-To | -| `GIT_PROTOCOL.md` | `reference/git-protocol.md` | Reference | -| `TEST_STRATEGY.md` | `reference/test-strategy.md` | Reference | -| *(new)* | `reference/configuration.md` | Reference | -| `ARCHITECTURE.md` | `explanation/architecture.md` | Explanation | -| `DECISION_SUMMARY.md` | `explanation/decisions.md` | Explanation | -| `COMPARISON.md` | `explanation/comparison.md` | Explanation | -| *(new)* | `explanation/inline-authorization.md` | Explanation | -| `learnings/` | **DEPRECATED** | *(distributed)* | - ---- - -## The Diátaxis Quadrants - -``` - PRACTICAL THEORETICAL - ───────── ─────────── - -LEARNING │ Tutorials │ Explanation │ - │ │ │ - │ "Can you │ "Why does │ - │ teach me?" │ this work?" │ - │ │ │ - ├────────────────┼──────────────────┤ - │ │ │ -WORKING │ How-To │ Reference │ - │ Guides │ │ - │ │ "What is the │ - │ "How do I?" │ syntax?" │ - │ │ │ -``` - -### When to Use Each Category - -**Tutorials** (`docs/tutorials/`) -- ✅ Teaching beginners -- ✅ Step-by-step lessons -- ✅ Guaranteed outcomes -- ❓ "Can you teach me to use ngit-grasp?" -- 📝 Example: Getting Started - -**How-To Guides** (`docs/how-to/`) -- ✅ Solving specific problems -- ✅ Practical recipes -- ✅ Assumes basic knowledge -- ❓ "How do I deploy ngit-grasp?" -- 📝 Example: Configure Nix Flakes - -**Reference** (`docs/reference/`) -- ✅ Technical specifications -- ✅ Factual information -- ✅ Comprehensive details -- ❓ "What are all the config options?" -- 📝 Example: Configuration Reference - -**Explanation** (`docs/explanation/`) -- ✅ Understanding concepts -- ✅ Design decisions -- ✅ Discussing alternatives -- ❓ "Why inline authorization?" -- 📝 Example: Architecture Overview - ---- - -## New Documentation Created - -### Tutorials -- ✅ `tutorials/getting-started.md` - Migrated and enhanced -- ✅ `tutorials/first-audit.md` - **NEW** - Learn grasp-audit - -### How-To Guides -- ✅ `how-to/nix-flakes.md` - Migrated from learnings - -### Reference -- ✅ `reference/configuration.md` - **NEW** - Complete config reference -- ✅ `reference/git-protocol.md` - Migrated -- ✅ `reference/test-strategy.md` - Migrated - -### Explanation -- ✅ `explanation/inline-authorization.md` - **NEW** - Deep dive on key decision -- ✅ `explanation/architecture.md` - Migrated -- ✅ `explanation/comparison.md` - Migrated -- ✅ `explanation/decisions.md` - Migrated - -### Category Indexes -- ✅ `tutorials/README.md` - Category guide -- ✅ `how-to/README.md` - Category guide -- ✅ `reference/README.md` - Category guide -- ✅ `explanation/README.md` - Category guide - -### Navigation -- ✅ `docs/README.md` - Main navigation with Diátaxis diagram -- ✅ `learnings/README.md` - Deprecation notice - ---- - -## Updated Files - -### Project Documentation -- ✅ `AGENTS.md` - Updated with Diátaxis guidelines -- ✅ `README.md` - Updated links to new structure - -### Moved Files -```bash -# Explanation -docs/ARCHITECTURE.md → docs/explanation/architecture.md -docs/COMPARISON.md → docs/explanation/comparison.md -docs/DECISION_SUMMARY.md → docs/explanation/decisions.md - -# Reference -docs/GIT_PROTOCOL.md → docs/reference/git-protocol.md -docs/TEST_STRATEGY.md → docs/reference/test-strategy.md - -# How-To -docs/learnings/nix-flakes.md → docs/how-to/nix-flakes.md -``` - ---- - -## For Content Authors - -### Creating New Documentation - -**Ask yourself:** - -1. **"Can you teach me to...?"** - - → Tutorial (`docs/tutorials/`) - - Example: "Can you teach me to deploy ngit-grasp?" - -2. **"How do I...?"** - - → How-To (`docs/how-to/`) - - Example: "How do I configure rate limiting?" - -3. **"What is...?"** - - → Reference (`docs/reference/`) - - Example: "What is the NGIT_DOMAIN variable?" - -4. **"Why...?"** - - → Explanation (`docs/explanation/`) - - Example: "Why use Rust instead of Go?" - -### Quick Decision Tree - -``` -Is it teaching a beginner from scratch? -├─ YES → Tutorial -└─ NO - └─ Is it solving a specific problem? - ├─ YES → How-To - └─ NO - └─ Is it factual/technical information? - ├─ YES → Reference - └─ NO → Explanation -``` - ---- - -## For Readers - -### Finding What You Need - -**I'm brand new:** -1. Start with [README.md](README.md) -2. Follow [Getting Started Tutorial](docs/tutorials/getting-started.md) -3. Read [Architecture Explanation](docs/explanation/architecture.md) - -**I have a specific problem:** -1. Check [How-To Guides](docs/how-to/) -2. Search for your problem -3. Follow the recipe - -**I need technical details:** -1. Check [Reference](docs/reference/) -2. Use search or table of contents -3. Look up what you need - -**I want to understand the design:** -1. Read [Explanation](docs/explanation/) -2. Start with [Architecture](docs/explanation/architecture.md) -3. Dive into specific decisions - ---- - -## Benefits of Diátaxis - -### For Authors -- ✅ Clear guidelines on where to put content -- ✅ Consistent structure across all docs -- ✅ Easy to know what style to use -- ✅ Less decision fatigue - -### 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 structure - ---- - -## Compliance with AGENTS.md - -Updated `AGENTS.md` to enforce Diátaxis: - -- ✅ Documentation structure section updated -- ✅ File lifecycle includes Diátaxis categories -- ✅ "Before creating documents" includes Diátaxis questions -- ✅ Cleanup process updated -- ✅ `learnings/` marked as deprecated - -**AI agents will now:** -- Ask Diátaxis questions before creating docs -- Place content in correct category -- Follow category-specific guidelines -- Maintain consistent structure - ---- - -## Migration Checklist - -- ✅ Create Diátaxis directory structure -- ✅ Migrate existing docs to appropriate categories -- ✅ Create new documentation (tutorials, how-to, reference) -- ✅ Create category README files -- ✅ Update main docs/README.md with Diátaxis diagram -- ✅ Update AGENTS.md with Diátaxis guidelines -- ✅ Mark learnings/ as deprecated -- ✅ Update project README.md links -- ✅ Create this migration document -- ✅ Test all internal links - ---- - -## Next Steps - -### Immediate -- ✅ Archive this document after review -- ✅ Update any broken links -- ✅ Commit all changes - -### Short-term -- 🔜 Complete planned how-to guides (deploy, test-compliance) -- 🔜 Migrate remaining learnings content -- 🔜 Add more tutorials as features complete - -### Long-term -- 🔜 Generate API reference from code -- 🔜 Add video tutorials -- 🔜 Create interactive examples -- 🔜 Translate to other languages - ---- - -## Resources - -- **[Diátaxis Framework](https://diataxis.fr/)** - Official documentation -- **[Diátaxis: How to use](https://diataxis.fr/how-to-use-diataxis/)** - Implementation guide -- **[Examples](https://diataxis.fr/examples/)** - Real-world examples - ---- - -## Questions? - -- Check [docs/README.md](docs/README.md) for navigation -- Read category README files for guidelines -- See [AGENTS.md](AGENTS.md) for contribution rules -- Open an issue if something is unclear - ---- - -**Migration completed:** November 4, 2025 -**Migrated by:** AI Agent (Dork) -**Framework:** [Diátaxis](https://diataxis.fr/) -**Status:** ✅ Complete and enforced - ---- - -*This document will be archived to `docs/archive/` after review.* -- cgit v1.2.3