blob: ccd0c8347b3a3b84aa07224e2fc10e4166e86cb7 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
|
# Learnings Directory - DEPRECATED
**Status:** This directory is deprecated as of November 4, 2025.
---
## What Happened?
We migrated to the **[Diátaxis](https://diataxis.fr/) documentation framework**, which provides a clearer structure based on content purpose rather than origin.
---
## Where Did Content Go?
The "learnings" were distributed into appropriate Diátaxis categories:
### Gotchas and Patterns → How-To Guides
- `nix-flakes.md` → [`docs/how-to/nix-flakes.md`](../how-to/nix-flakes.md)
- Task-oriented solutions to common problems
### Technical Details → Reference
- `nostr-sdk.md` → [`docs/reference/nostr-sdk-upgrade.md`](../reference/nostr-sdk-upgrade.md) (planned)
- `git-http-backend.md` → [`docs/reference/git-protocol.md`](../reference/git-protocol.md)
- Factual technical information
### Concepts and Understanding → Explanation
- `grasp-audit.md` → Incorporated into [`docs/explanation/architecture.md`](../explanation/architecture.md)
- Discussion of design and architecture
---
## Why the Change?
The "learnings" category was ambiguous:
- Mixed gotchas, patterns, and concepts
- Unclear where to put new content
- Hard for readers to know what to expect
**Diátaxis provides clear categories:**
- **Tutorials** - Learning by doing
- **How-To** - Solving problems
- **Reference** - Looking up facts
- **Explanation** - Understanding concepts
See [`docs/README.md`](../README.md) for the new structure.
---
## For Content Authors
**Don't create new files here.** Instead, ask:
- "Can you teach me to...?" → [`docs/tutorials/`](../tutorials/)
- "How do I...?" → [`docs/how-to/`](../how-to/)
- "What is...?" → [`docs/reference/`](../reference/)
- "Why...?" → [`docs/explanation/`](../explanation/)
---
## Migration Status
- ✅ `nix-flakes.md` → Migrated to `how-to/nix-flakes.md`
- ⏳ `nostr-sdk.md` → Being incorporated into reference docs
- ✅ `grasp-audit.md` → Content in `explanation/architecture.md`
---
*This directory will be removed in a future cleanup.*
*See [AGENTS.md](../../AGENTS.md) for documentation guidelines.*
|