upleb.uk

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

summaryrefslogtreecommitdiff
path: root/docs/tutorials/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/tutorials/README.md')
-rw-r--r--docs/tutorials/README.md116
1 files changed, 116 insertions, 0 deletions
diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md
new file mode 100644
index 0000000..3eb0c5c
--- /dev/null
+++ b/docs/tutorials/README.md
@@ -0,0 +1,116 @@
1# Tutorials
2
3**Learning-oriented documentation** - Learn by doing with step-by-step guidance.
4
5---
6
7## What Are Tutorials?
8
9Tutorials are **lessons** that teach you how to use ngit-grasp through practical, hands-on steps.
10
11**Characteristics:**
12- ✅ Learning-oriented (teach beginners)
13- ✅ Practical (you follow along)
14- ✅ Step-by-step with guaranteed outcomes
15- ✅ Complete from start to finish
16- ✅ Safe to experiment with
17
18**Not tutorials:**
19- ❌ Problem-solving guides (those are How-To)
20- ❌ Technical references (those are Reference)
21- ❌ Conceptual explanations (those are Explanation)
22
23---
24
25## Available Tutorials
26
27### [Getting Started](getting-started.md)
28**Time:** 15-20 minutes
29**Learn:** Set up ngit-grasp development environment, build and test the code
30
31**You'll accomplish:**
32- Clone and build the project
33- Set up Nix development environment
34- Run tests successfully
35- Understand project structure
36
37**Start here if:** You're brand new to ngit-grasp
38
39---
40
41### [Running Your First Audit](first-audit.md)
42**Time:** 10-15 minutes
43**Prerequisites:** [Getting Started](getting-started.md) completed
44**Learn:** Use grasp-audit to check GRASP compliance
45
46**You'll accomplish:**
47- Run compliance tests against a relay
48- Interpret audit results
49- Use the audit tool library
50- Understand GRASP requirements
51
52**Start here if:** You want to test GRASP compliance
53
54---
55
56## Planned Tutorials
57
58### Deploying Your First GRASP Relay
59**Status:** 🔜 Planned (waiting for main server implementation)
60
61**You'll learn:**
62- Deploy ngit-grasp to production
63- Configure for your domain
64- Set up HTTPS with reverse proxy
65- Create your first repository
66
67---
68
69### Contributing Your First PR
70**Status:** 🔜 Planned
71
72**You'll learn:**
73- Find an issue to work on
74- Set up development environment
75- Make changes and test
76- Submit a pull request
77
78---
79
80## How to Use Tutorials
81
821. **Follow in order** - Each step builds on previous ones
832. **Actually do the steps** - Don't just read, type the commands
843. **Expect success** - If something fails, check troubleshooting
854. **Learn by doing** - Understanding comes from practice
86
87**Not sure if this is what you need?**
88- Want to solve a specific problem? → [How-To Guides](../how-to/)
89- Looking for technical details? → [Reference](../reference/)
90- Want to understand the design? → [Explanation](../explanation/)
91
92---
93
94## Contributing Tutorials
95
96When writing a tutorial:
97
98**DO:**
99- ✅ Start with a clear learning goal
100- ✅ Provide complete, tested steps
101- ✅ Include expected output
102- ✅ Add troubleshooting section
103- ✅ Keep it focused (one topic)
104- ✅ Test with a beginner
105
106**DON'T:**
107- ❌ Assume prior knowledge (or state prerequisites clearly)
108- ❌ Skip steps ("obviously you would...")
109- ❌ Explain every detail (link to Explanation docs)
110- ❌ Try to cover everything (keep scope small)
111
112See [Diátaxis: Tutorials](https://diataxis.fr/tutorials/) for detailed guidance.
113
114---
115
116*Part of the [ngit-grasp documentation](../README.md) using the [Diátaxis](https://diataxis.fr/) framework.*