Rules for Writing Software Tutorials

Most software tutorials are tragically flawed.

Tutorials often forget to mention some key detail, preventing readers from replicating the author’s process. Other times, the author brings in hidden assumptions that don’t match their readers’ expectations.

The good news is that it’s easier than you think to write an exceptional software tutorial. You can stand out in a sea of mediocre guides by following a few simple rules.

Rules

1. Write for beginners
2. Promise a clear outcome in the title
3. Explain the goal in the introduction
4. Show the end result
5. Make code snippets copy/pasteable
6. Use long versions of command-line flags
7. Separate user-defined values from reusable logic
8. Use unambiguous example values
9. Spare the reader from mindless tasks
10. Keep your code in a working state
11. Teach one thing
12. Don’t try to look pretty
13. Minimize dependencies
14. Specify filenames clearly
15. Use consistent, descriptive headings
16. Demonstrate that your solution works
17. Link to a complete example

Write for beginners

The most common mistake tutorials make is explaining beginner-level concepts using expert-level terminology.