blob: 087ae5354f74c679d3530189f38d1a090f3dc423 (
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
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
# How-To Guides
**Task-oriented documentation** - Practical solutions to common problems.
---
## What Are How-To Guides?
How-to guides are **recipes** that show you how to solve specific problems or accomplish particular tasks.
**Characteristics:**
- ✅ Task-oriented (solve a problem)
- ✅ Practical (actionable steps)
- ✅ Assume basic knowledge
- ✅ Focus on results
- ✅ Can be followed in any order
**Not how-to guides:**
- ❌ Complete lessons for beginners (those are Tutorials)
- ❌ Technical specifications (those are Reference)
- ❌ Conceptual discussions (those are Explanation)
---
## Available How-To Guides
### [Configure Nix Flakes](nix-flakes.md)
**Problem:** Set up reproducible development environment
**Difficulty:** Intermediate
**You'll learn:**
- Enable Nix flakes
- Enter development environment
- Work with subprojects
- Troubleshoot common issues
---
### [Test Sync Against Production Data](production-sync-testing.md)
**Problem:** Debug and improve sync using real-world data
**Difficulty:** Intermediate
**You'll learn:**
- Run sync against production relays
- Sanitize logs for LLM analysis
- Identify common issues and patterns
- Iteratively improve sync behavior
---
## Planned How-To Guides
### Deploy ngit-grasp
**Status:** 🔜 Planned (waiting for main server)
**Problem:** Deploy to production
**You'll learn:**
- Server requirements
- Reverse proxy setup (nginx/Caddy)
- SSL/TLS configuration
- Monitoring and logging
---
### Run Compliance Tests
**Status:** 🔜 Planned
**Problem:** Test GRASP compliance
**You'll learn:**
- Set up test relay
- Run integration tests
- Interpret results
- Add custom tests
---
### Upgrade nostr-sdk
**Status:** 🔜 Planned
**Problem:** Handle breaking changes in nostr-sdk
**You'll learn:**
- Check for breaking changes
- Update dependencies
- Fix compilation errors
- Test after upgrade
---
### Configure Authentication
**Status:** 🔜 Planned (feature not yet implemented)
**Problem:** Secure your relay
**You'll learn:**
- Enable authentication
- Configure allowed users
- Set up rate limiting
- Monitor access
---
### Backup and Restore
**Status:** 🔜 Planned
**Problem:** Protect your data
**You'll learn:**
- Backup Git repositories
- Backup Nostr events
- Restore from backup
- Automate backups
---
## How to Use How-To Guides
1. **Find your problem** - Browse or search for what you need
2. **Check prerequisites** - Make sure you have required knowledge
3. **Follow the steps** - Adapt to your specific situation
4. **Solve and move on** - No need to read everything
**Not sure if this is what you need?**
- New to ngit-grasp? → [Tutorials](../tutorials/)
- Looking for technical details? → [Reference](../reference/)
- Want to understand why? → [Explanation](../explanation/)
---
## Contributing How-To Guides
When writing a how-to guide:
**DO:**
- ✅ Start with the problem/goal
- ✅ List prerequisites clearly
- ✅ Provide concrete steps
- ✅ Include troubleshooting
- ✅ Show examples
- ✅ Link to related docs
**DON'T:**
- ❌ Teach basics (link to Tutorials)
- ❌ Explain every concept (link to Explanation)
- ❌ List all options (link to Reference)
- ❌ Make it a tutorial (stay focused on the task)
**Template:**
```markdown
# How-To: [Task/Problem]
**Problem:** [What you're trying to accomplish]
**Difficulty:** [Beginner/Intermediate/Advanced]
**Time:** [Estimated time]
## Prerequisites
- [Required knowledge/tools]
## Solution
### Step 1: [Action]
[Instructions]
### Step 2: [Action]
[Instructions]
## Troubleshooting
### [Common problem]
**Solution:** [How to fix]
## Related Documentation
- [Links to relevant docs]
```
See [Diátaxis: How-To Guides](https://diataxis.fr/how-to-guides/) for detailed guidance.
---
*Part of the [ngit-grasp documentation](../README.md) using the [Diátaxis](https://diataxis.fr/) framework.*
|