upleb.uk

Public git repos — served from a NIP-34 GRASP relay at git.upleb.uk

summaryrefslogtreecommitdiff
path: root/docs/archive/2025-11-04-diataxis-migration-visual.txt
diff options
context:
space:
mode:
authorDanConwayDev <DanConwayDev@protonmail.com>2025-12-03 11:19:40 +0000
committerDanConwayDev <DanConwayDev@protonmail.com>2025-12-03 11:19:40 +0000
commit2eaff5b79fed364d5eba5eb38e4b7bf76326884d (patch)
treedeacd6294f8860096ee82ee76930204efd65e33c /docs/archive/2025-11-04-diataxis-migration-visual.txt
parent57bc8cd9c021feaf08e139e8fb62800bc476068e (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.txt218
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
13LEARNING │ Tutorials │ Explanation │
14 │ │ │
15 │ Getting │ Architecture │
16 │ Started │ Inline Auth │
17 │ First Audit │ Comparison │
18 │ │ Decisions │
19 │ │ │
20 ├────────────────┼──────────────────┤
21 │ │ │
22WORKING │ 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
35docs/
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
76CREATED (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
89MIGRATED (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
97UPDATED (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
107When 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
146FOR 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
153FOR 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
160FOR 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
172NAVIGATION:
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
179GUIDELINES:
180 For AI agents ........ AGENTS.md (Diátaxis enforcement)
181 For contributors ..... Each category README.md
182 For migration ........ DIATAXIS_MIGRATION.md
183
184EXTERNAL:
185 Framework ............ https://diataxis.fr/
186 Examples ............. https://diataxis.fr/examples/
187
188
189┌──────────────────────────────────────────────────────────────────────────────┐
190│ NEXT STEPS │
191└──────────────────────────────────────────────────────────────────────────────┘
192
193IMMEDIATE:
194 ✅ Archive this visual summary to docs/archive/
195 ✅ Archive DIATAXIS_MIGRATION.md after review
196 ✅ Commit all changes
197
198SHORT-TERM:
199 🔜 Complete planned how-to guides (deploy, test-compliance)
200 🔜 Migrate remaining learnings content
201 🔜 Add more tutorials as features complete
202
203LONG-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╚══════════════════════════════════════════════════════════════════════════════╝