What to write about?
Start with the subtopic.
Have a list of 20-50 ideas for tutorials for each subtopic.
Get ideas from other books, courses, blogs, and communities.
Anytime there is a comment or email on the subtopic that is not in the list or on the site, add it to the list.
The best tutorials will provide the basis of products, e.g. ebooks.
A tutorial belongs to one subtopic of the site.
A tutorial does one thing.
It has a specific goal for the reader.
Anything not related to the one problem solved by the tutorial is linked.
State the goal of the tutorial at the top before writing, and keep coming back to it.
The goal of this tutorial is to show the reader how to...
What is the structure of a tutorial?
I like to structure tutorials like sales letters.
A common structure for a tutorial is PAS: problem, agitate, solve.
- Problem: Describe the situation and the problem.
- Agitate: Describe why the problem is a problem and the difficulty it can cause.
- Solve: Describe the technique used to solve the problem.
The solution may involve first describing the technique, then providing a code example.
A variation of this structure is:
- Problem: Describe the situation and the problem.
- Solution: Describe the general technique used to solve the problem.
- Code: Provide a specific worked example on how to use the technique.
I used this pattern a lot. Another variation I like is the 4Mat:
- Why: Describe the situation and the problem, e.g. why do we care?
- What: Describe the solution, e.g. what is it?
- How: Describe how to implement a solution, e.g. how do you do it?
- What If: Describe how to customize and address doubts, e.g. you can do this if...
Every tutorial needs to be actionable.
The reader must come in with the problem. See that the author understands the problem as well or better that the reader. Understand the general approach to solving the problem. Leave with a working code example that be adapted for their project. Know what books and APIs to read if they need more detail.
Do this again and again, and the author/brand builds trust with the reader.
- The reader keeps coming back.
- The reader recommends the site.
- The reader converts to prospect and customer.
What elements can be included?
Every tutorial must have a featured image.
Every tutorial must have an introduction that describes the problem, the problem of the problem, and the solution.
Every tutorial must summarize the three take aways of the tutorial.
Every tutorial must have a resources section where the reader can go to get more information on the specific problem.
Tutorials can quote experts from books and papers. This will be ideas already stated in the main copy to reinforce the point and to borrow authority.
Tutorials almost always have code examples when solving a technical problem. Tutorials that don't might include high-level introductions to a topic, background, resource lists, etc.
Diagrams are good. Custom made diagrams are best.
What's a standard structure?
- heading how to x with y, a gentle introduction to z, etc.
- intro: what the problem and solution, what will be learned, what are the 3 take aways
- problem: the situation and the problem in the situation
- solution: the general technique used to solve the problem and how it works
- code example: step by step implementaiton that builds up funtions and funally a complete solution
- address doubts and customizatios: you can do this even if... you cannot do this if, to can change this to..
- extensions: what are 3-5 ways can extend the example as a learning exercise
- resources: what are books, appers, posts and apis I can read to learn more detail
- conclusion: what was learned and what are the three takeaways.
Do not show off.
Do not over complicate.
Do not obfuscate.
Do not go beyond the goal, the scope.
Do not make assumptions about the readers skill level or knowledge level.
Do not steal.
How to best present code?
Very simple code.
Few or no compound statements. Each line of code does one thing.
Lots of comments. Explain every line, within reason.
Build up the explanation in steps with code snippets then present the entire piece as a function or working example at the end of a section.
Make it clear that a snippet is incomplete with elipses before and/or after.
Make it clear that a listing is a complete working example with expected output.
Always interpret the output for the reader.
If the output of the code is stochastic, make this clear.
Explain or link to what development environment is required and how to install required libraries.
What voice to use?
You are working together with the reader.
You are not talking down to the reader.
You are pair programming and stepping through how to implement a solution and what things mean.
Use "we" a lot in the body of the tutorial, e.g. "next, we will..."
Use "you" a lot in the header and footer of the tutorial a lot, e.g. "you will learn..., you learned how to..."
What about SEO?
- tutorial title is h1
- sections are h2, subsections are h3 and so on
All images have a caption and descriptive alt text.
If there are steps in the solution, they should be numbered.
If a concept is being defined, then it should be defined directly with no preamble, e.g. so it can be used as a snippet by google.
Short sentences with no fluff.
Lots of white space.
First line of a section must be treated as a hook like in sales copy.
The top of the tutorial must tell them exactly what they will learn.
The end of the tutorial must remind them of what they have learned.
Ask the reader whether they have questions and to post questions in the comments.