In my opinion, onboarding documentation is one of the hardest kinds of writing to do well. The audience is regularly the people you cannot ask, and the success condition is invisible until someone you have never met succeeds without your help.
The cleanest practitioner reference I know on this craft is Docs for Developers: An Engineer’s Field Guide to Technical Writing, co-authored by documentation engineers from Google, Stripe, Monzo, and elsewhere.
Four things from that book are worth carrying into any future attempt:
-
A guide that gets one stranger through the first 30 minutes is worth more than a 12-module survey the author has personally verified. A tutorial is defined by a learner’s journey, not a topic outline.
-
Recruit at least one developer with no prior relevant exposure to follow the guide cold, on their own machine, while you watch silently. Where they stop is the guide’s real edge.
-
Publish a thin slice, run it past two or three real readers, revise, then expand. A finished-looking doc that no outside reader has run is the fragile shape.
-
Pairing with one or two builders who recently walked the path themselves makes the guide much harder to get wrong. The reason is that the longer you have known something, the harder it becomes to model what it feels like not to know it.
None of this is Spark committee preference. And we are looking forward to more and more guides that finally let a stranger reach their first CKB success on their own machine.