path: root/docs/archive/2025-11-04-diataxis-migration.md

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