Write a tutorial that lasts
How to write a tutorial for the Community: a cover, one step per heading, show the result, split long guides into a series with parts.
A good tutorial is read for years by people who never meet its author. That is a small miracle, and it is mostly made of habits, not talent.
Start from the end#
Open with what the reader will have when they are done. "You will plug your own app into Geenius OS so that people can sign in with one button" tells them whether to read on. If you cannot say it in a sentence, the tutorial is trying to do too much.
One step, one heading#
Number the steps and give each its own heading. A reader who gets stuck at step four must be able to find step four again. Keep each step to one action and the result you should see after it.
Show the result#
After every command or click, say what should happen. If it does not, the reader knows they went wrong at that step and not three steps later. Where a value changes between people, name it in code formatting and say where to find theirs.
Use markdown properly#
Community takes markdown bodies. Use headings for steps, lists for options, and code blocks for commands and responses. Add a cover so that the post stands out in the channel, and up to five tags so that search finds it.
Split long guides into a series#
If your guide has more than a handful of steps, split it. A series has a name and each post a part number, and readers see the parts together. The first series in the Geenius Community is the team's own, Building on the registry, whose first part takes an app through registration in five steps. Writing parts also gives you a reason to publish sooner.
Say where to ask#
End with the channel where questions belong. The Developers side has Dev questions for exactly this. A tutorial with a place to ask is a tutorial that gets corrected, and a corrected tutorial lasts.
Be honest about its age#
Name the version of what you used and the date you wrote it. If something changes, edit the post. You can edit your own posts, and a note at the top that says what changed is kinder than letting a wrong step stand.
Read about tutorials and series or look at what developers do here.