In addition to the previous advice on what a guide should be and what is mandatory, you should pay special attention to the following points:
Each step should be concise, but not too short
Be wary of a step’s length. On average, 5 to 10 minutes is more than enough for a single step to complete. Don’t make them too short either. Naturally, some steps will be shorter than others (such as the first and last steps).
If too long, prefer dividing the guide
Tutorials are self-sufficient, but they can nonetheless build upon each other (you can link from the requirements section of the first step, for example). One guide could require another guide to be completed first. And if you are reusing the same code, ensure you provide a repository as a starting point.
If a guide is too long, consider breaking it up into several pieces. However, ensure all guides present a distinct objective.
Don’t have too many steps
Steps should be concise and guides should be rather short. Consequently, you shouldn’t have too many steps in your guide. We don’t want to make the reader desperate by glancing at the number of remaining steps before guide completion.
Each step should be rewarding
As a writer, you should try to keep the reader entertained at each step and this is achieved by careful story building. Each step should end on concrete progress towards the end goal. It should be, if possible, tangible and interactive, so that the reader can be familiarised with notions introduced by the step.
To earn bonus reader commitment points, finish a step on a “cliffhanger”!
Make intentional mistakes
This could seem counterintuitive at first. However, learning by fire (or rather, by error here) is a key way of learning new things. Executing, erroring, analyzing and fixing has multiple benefits:
Users will be familiar with a particular error, and even if they don’t remember explicitly how to fix it the next time they encounter it, they will have some clue and some deja-vu feeling which will guide them towards its resolution.
Providing the perfect answer from the start hides complexity and a lot of non-formally written subtleties. Forcing readers to face them will ensure that the guide written doesn’t take these subtleties as a given and will greatly help newcomers.
A concrete example of this is, in the “Create your first snap” guide, how we introduce building a snap. After creating the parts, we immediately build the snap and install it. Then, we try to execute one of the snap binaries, but no such command is found! That way, we can introduce the fact (in the following step) that binaries are not exposed by default as part of the snap. We can use this “mistake” to introduce further concepts.
External links in guides
Links to external websites are forbidden during a guide. We don’t want people’s attention diverted from the task they are going through (which emphasizes the fact that each step should have enough knowledge to be self-sufficient). In particular, do not link the reader to the reference documentation. We want to keep the user’s attention on the current task only. Download links are allowed though.
As previously written, only the first and last steps can (and probably should) link to external documentation for prerequisites or learning more on a particular topic. The same rule applies to external websites for libraries or frameworks.
The only exception to this rule is when linking to source code that is being used as a checkpoint in the guide (eg. “your code should look like this”).
Of course, this doesn’t concern key guide actions happening on a given website, like Launchpad, GitHub, login.ubuntu.com, etc.
Provide regular code “checkpoints”
This is mostly for developer oriented guides, but if this rule can be applied to an admin/advanced users oriented one, please do so!
The advice is to provide regular checkpoints where people can sync back their source code with the guide, in particular, at the start of a given step. Readers could have stopped then resumed going through a guide, and may not have the source code from previous steps anymore. Consequently, in the case of a code-writing guide, please try to provide a link to the current state of the code at the start of a step.
You can refer to it as “If you want to ensure you have all the needed bits we saw together in the previous steps…“ and point to an external repository on GitHub, Launchpad or others… This element should be in an admonition:
Lost or starting from here?
[download](http://link/torepo/directory) to see what your current directory should look like.
“download” being a link to the code in question.
Do not separate exercises and answers
In general, try to avoid leaving the user hanging for the right answer. Tutorials aren’t a class/lesson or a test to pass with some exercises.
In particular, to avoid a teacher/student relationship, do not separate questions and answers (apart from cliffhangers as previously stated, but the questions you are asking your audience are more rhetorical in that case!).
Do not repeat the setup/install phase for each guide
Avoid repetitive setups or installation phases, particularly if the guide isn’t a beginner one. Beginner guides should contain a setup phase while more advanced guides should reference other beginner guides as prerequisites.
Command line snippets
Inline commands are styled with single backticks :
Which renders as
For longer example code we expect people to type in, we do not use the command prompt at the beginning of each line, and we separate the command from the output. This makes the command and outputs clearer and also easier to copy and paste.
` Run the following command:
This will display the content of the file:
Awesome my_file content
on multiple lines
Finally, the code blocks (commands and code to write) of the guide should be self-sufficient. It means that we don’t expect people to write code or run commands outside of what we expose in code blocks, and only typing and executing their content should lead them to the desired state.
You should now have all the cards in hand to provide a rewarding learning experience! It’s time we look at how to structure the final page of a guide: the “rewarding” step.