diff options
| author | DanConwayDev <DanConwayDev@protonmail.com> | 2025-12-03 11:19:40 +0000 |
|---|---|---|
| committer | DanConwayDev <DanConwayDev@protonmail.com> | 2025-12-03 11:19:40 +0000 |
| commit | 2eaff5b79fed364d5eba5eb38e4b7bf76326884d (patch) | |
| tree | deacd6294f8860096ee82ee76930204efd65e33c /docs/archive/2025-11-04-diataxis-migration-visual.txt | |
| parent | 57bc8cd9c021feaf08e139e8fb62800bc476068e (diff) | |
remove docs archive
Diffstat (limited to 'docs/archive/2025-11-04-diataxis-migration-visual.txt')
| -rw-r--r-- | docs/archive/2025-11-04-diataxis-migration-visual.txt | 218 |
1 files changed, 0 insertions, 218 deletions
diff --git a/docs/archive/2025-11-04-diataxis-migration-visual.txt b/docs/archive/2025-11-04-diataxis-migration-visual.txt deleted file mode 100644 index d6d54e2..0000000 --- a/docs/archive/2025-11-04-diataxis-migration-visual.txt +++ /dev/null | |||
| @@ -1,218 +0,0 @@ | |||
| 1 | ╔══════════════════════════════════════════════════════════════════════════════╗ | ||
| 2 | ║ DIÁTAXIS MIGRATION COMPLETE ✅ ║ | ||
| 3 | ║ November 4, 2025 ║ | ||
| 4 | ╚══════════════════════════════════════════════════════════════════════════════╝ | ||
| 5 | |||
| 6 | ┌──────────────────────────────────────────────────────────────────────────────┐ | ||
| 7 | │ THE DIÁTAXIS FRAMEWORK │ | ||
| 8 | └──────────────────────────────────────────────────────────────────────────────┘ | ||
| 9 | |||
| 10 | PRACTICAL THEORETICAL | ||
| 11 | ───────── ─────────── | ||
| 12 | |||
| 13 | LEARNING │ Tutorials │ Explanation │ | ||
| 14 | │ │ │ | ||
| 15 | │ Getting │ Architecture │ | ||
| 16 | │ Started │ Inline Auth │ | ||
| 17 | │ First Audit │ Comparison │ | ||
| 18 | │ │ Decisions │ | ||
| 19 | │ │ │ | ||
| 20 | ├────────────────┼──────────────────┤ | ||
| 21 | │ │ │ | ||
| 22 | WORKING │ How-To │ Reference │ | ||
| 23 | │ Guides │ │ | ||
| 24 | │ │ Configuration │ | ||
| 25 | │ Nix Flakes │ Git Protocol │ | ||
| 26 | │ Deploy │ Test Strategy │ | ||
| 27 | │ Testing │ GRASP Spec │ | ||
| 28 | │ │ │ | ||
| 29 | |||
| 30 | |||
| 31 | ┌──────────────────────────────────────────────────────────────────────────────┐ | ||
| 32 | │ DOCUMENTATION STRUCTURE │ | ||
| 33 | └──────────────────────────────────────────────────────────────────────────────┘ | ||
| 34 | |||
| 35 | docs/ | ||
| 36 | ├── README.md ..................... Main navigation with Diátaxis diagram | ||
| 37 | │ | ||
| 38 | ├── tutorials/ .................... 📚 Learning-oriented | ||
| 39 | │ ├── README.md ................. Category guide | ||
| 40 | │ ├── getting-started.md ........ ✅ First-time setup | ||
| 41 | │ └── first-audit.md ............ ✅ NEW: Learn grasp-audit | ||
| 42 | │ | ||
| 43 | ├── how-to/ ....................... 🔧 Task-oriented | ||
| 44 | │ ├── README.md ................. Category guide | ||
| 45 | │ ├── nix-flakes.md ............. ✅ Migrated from learnings/ | ||
| 46 | │ ├── deploy.md ................. 🔜 Planned | ||
| 47 | │ ├── test-compliance.md ........ 🔜 Planned | ||
| 48 | │ └── upgrade-nostr-sdk.md ...... 🔜 Planned | ||
| 49 | │ | ||
| 50 | ├── reference/ .................... 📖 Information-oriented | ||
| 51 | │ ├── README.md ................. Category guide | ||
| 52 | │ ├── configuration.md .......... ✅ NEW: Complete config reference | ||
| 53 | │ ├── git-protocol.md ........... ✅ Migrated from docs/ | ||
| 54 | │ ├── test-strategy.md .......... ✅ Migrated from docs/ | ||
| 55 | │ ├── grasp-protocol.md ......... 🔜 Planned | ||
| 56 | │ └── api.md .................... 🔜 Planned | ||
| 57 | │ | ||
| 58 | ├── explanation/ .................. 💡 Understanding-oriented | ||
| 59 | │ ├── README.md ................. Category guide | ||
| 60 | │ ├── architecture.md ........... ✅ Migrated from docs/ | ||
| 61 | │ ├── inline-authorization.md ... ✅ NEW: Deep dive on key decision | ||
| 62 | │ ├── comparison.md ............. ✅ Migrated from docs/ | ||
| 63 | │ └── decisions.md .............. ✅ Migrated from docs/ | ||
| 64 | │ | ||
| 65 | ├── archive/ ...................... 📦 Historical | ||
| 66 | │ └── YYYY-MM-DD-*.md ........... Session notes | ||
| 67 | │ | ||
| 68 | └── learnings/ .................... ⚠️ DEPRECATED | ||
| 69 | └── README.md ................. Migration notice | ||
| 70 | |||
| 71 | |||
| 72 | ┌──────────────────────────────────────────────────────────────────────────────┐ | ||
| 73 | │ MIGRATION SUMMARY │ | ||
| 74 | └──────────────────────────────────────────────────────────────────────────────┘ | ||
| 75 | |||
| 76 | CREATED (New Documentation): | ||
| 77 | ✅ docs/README.md ................. Main navigation with Diátaxis | ||
| 78 | ✅ tutorials/getting-started.md ... Migrated + enhanced | ||
| 79 | ✅ tutorials/first-audit.md ....... NEW: grasp-audit tutorial | ||
| 80 | ✅ how-to/nix-flakes.md ........... Migrated from learnings/ | ||
| 81 | ✅ reference/configuration.md ..... NEW: Complete config reference | ||
| 82 | ✅ explanation/inline-authorization.md . NEW: Deep dive | ||
| 83 | ✅ tutorials/README.md ............ Category guide | ||
| 84 | ✅ how-to/README.md ............... Category guide | ||
| 85 | ✅ reference/README.md ............ Category guide | ||
| 86 | ✅ explanation/README.md .......... Category guide | ||
| 87 | ✅ learnings/README.md ............ Deprecation notice | ||
| 88 | |||
| 89 | MIGRATED (Moved to Diátaxis): | ||
| 90 | ✅ ARCHITECTURE.md → explanation/architecture.md | ||
| 91 | ✅ COMPARISON.md → explanation/comparison.md | ||
| 92 | ✅ DECISION_SUMMARY.md → explanation/decisions.md | ||
| 93 | ✅ GIT_PROTOCOL.md → reference/git-protocol.md | ||
| 94 | ✅ TEST_STRATEGY.md → reference/test-strategy.md | ||
| 95 | ✅ learnings/nix-flakes.md → how-to/nix-flakes.md | ||
| 96 | |||
| 97 | UPDATED (Enforcement): | ||
| 98 | ✅ AGENTS.md ...................... Diátaxis guidelines | ||
| 99 | ✅ README.md ...................... Links to new structure | ||
| 100 | ✅ DIATAXIS_MIGRATION.md .......... This migration doc | ||
| 101 | |||
| 102 | |||
| 103 | ┌──────────────────────────────────────────────────────────────────────────────┐ | ||
| 104 | │ DECISION FRAMEWORK │ | ||
| 105 | └──────────────────────────────────────────────────────────────────────────────┘ | ||
| 106 | |||
| 107 | When creating new documentation, ask: | ||
| 108 | |||
| 109 | ┌─────────────────────────────────────┐ | ||
| 110 | │ "Can you teach me to...?" │ → TUTORIAL | ||
| 111 | │ │ | ||
| 112 | │ Teaching from scratch │ docs/tutorials/ | ||
| 113 | │ Step-by-step lesson │ | ||
| 114 | │ Guaranteed outcome │ | ||
| 115 | └─────────────────────────────────────┘ | ||
| 116 | |||
| 117 | ┌─────────────────────────────────────┐ | ||
| 118 | │ "How do I...?" │ → HOW-TO | ||
| 119 | │ │ | ||
| 120 | │ Solving specific problem │ docs/how-to/ | ||
| 121 | │ Practical recipe │ | ||
| 122 | │ Assumes basic knowledge │ | ||
| 123 | └─────────────────────────────────────┘ | ||
| 124 | |||
| 125 | ┌─────────────────────────────────────┐ | ||
| 126 | │ "What is...?" │ → REFERENCE | ||
| 127 | │ │ | ||
| 128 | │ Technical specification │ docs/reference/ | ||
| 129 | │ Factual information │ | ||
| 130 | │ Comprehensive details │ | ||
| 131 | └─────────────────────────────────────┘ | ||
| 132 | |||
| 133 | ┌─────────────────────────────────────┐ | ||
| 134 | │ "Why...?" │ → EXPLANATION | ||
| 135 | │ │ | ||
| 136 | │ Understanding concepts │ docs/explanation/ | ||
| 137 | │ Design decisions │ | ||
| 138 | │ Discussing alternatives │ | ||
| 139 | └─────────────────────────────────────┘ | ||
| 140 | |||
| 141 | |||
| 142 | ┌──────────────────────────────────────────────────────────────────────────────┐ | ||
| 143 | │ BENEFITS │ | ||
| 144 | └──────────────────────────────────────────────────────────────────────────────┘ | ||
| 145 | |||
| 146 | FOR AUTHORS: | ||
| 147 | ✅ Clear guidelines on where to put content | ||
| 148 | ✅ Consistent structure across all docs | ||
| 149 | ✅ Easy to know what style to use | ||
| 150 | ✅ Less decision fatigue | ||
| 151 | ✅ Industry best practice | ||
| 152 | |||
| 153 | FOR READERS: | ||
| 154 | ✅ Know what to expect from each doc | ||
| 155 | ✅ Easy to find what you need | ||
| 156 | ✅ Can navigate by purpose | ||
| 157 | ✅ Better learning experience | ||
| 158 | ✅ Clear reading paths | ||
| 159 | |||
| 160 | FOR MAINTAINERS: | ||
| 161 | ✅ Easier to review contributions | ||
| 162 | ✅ Clearer documentation standards | ||
| 163 | ✅ Less duplicate content | ||
| 164 | ✅ Sustainable structure | ||
| 165 | ✅ Enforced by AGENTS.md | ||
| 166 | |||
| 167 | |||
| 168 | ┌──────────────────────────────────────────────────────────────────────────────┐ | ||
| 169 | │ QUICK REFERENCE │ | ||
| 170 | └──────────────────────────────────────────────────────────────────────────────┘ | ||
| 171 | |||
| 172 | NAVIGATION: | ||
| 173 | Start here ........... docs/README.md (Diátaxis diagram + paths) | ||
| 174 | For beginners ........ docs/tutorials/getting-started.md | ||
| 175 | For problems ......... docs/how-to/ | ||
| 176 | For lookups .......... docs/reference/ | ||
| 177 | For understanding .... docs/explanation/ | ||
| 178 | |||
| 179 | GUIDELINES: | ||
| 180 | For AI agents ........ AGENTS.md (Diátaxis enforcement) | ||
| 181 | For contributors ..... Each category README.md | ||
| 182 | For migration ........ DIATAXIS_MIGRATION.md | ||
| 183 | |||
| 184 | EXTERNAL: | ||
| 185 | Framework ............ https://diataxis.fr/ | ||
| 186 | Examples ............. https://diataxis.fr/examples/ | ||
| 187 | |||
| 188 | |||
| 189 | ┌──────────────────────────────────────────────────────────────────────────────┐ | ||
| 190 | │ NEXT STEPS │ | ||
| 191 | └──────────────────────────────────────────────────────────────────────────────┘ | ||
| 192 | |||
| 193 | IMMEDIATE: | ||
| 194 | ✅ Archive this visual summary to docs/archive/ | ||
| 195 | ✅ Archive DIATAXIS_MIGRATION.md after review | ||
| 196 | ✅ Commit all changes | ||
| 197 | |||
| 198 | SHORT-TERM: | ||
| 199 | 🔜 Complete planned how-to guides (deploy, test-compliance) | ||
| 200 | 🔜 Migrate remaining learnings content | ||
| 201 | 🔜 Add more tutorials as features complete | ||
| 202 | |||
| 203 | LONG-TERM: | ||
| 204 | 🔜 Generate API reference from code | ||
| 205 | 🔜 Add video tutorials | ||
| 206 | 🔜 Create interactive examples | ||
| 207 | |||
| 208 | |||
| 209 | ╔══════════════════════════════════════════════════════════════════════════════╗ | ||
| 210 | ║ ║ | ||
| 211 | ║ ✅ DIÁTAXIS MIGRATION COMPLETE ║ | ||
| 212 | ║ ║ | ||
| 213 | ║ Documentation now follows industry ║ | ||
| 214 | ║ best practice for technical writing ║ | ||
| 215 | ║ ║ | ||
| 216 | ║ https://diataxis.fr/ ║ | ||
| 217 | ║ ║ | ||
| 218 | ╚══════════════════════════════════════════════════════════════════════════════╝ | ||