mathspp
  • Blog
    • Pydon'ts
    • Problems
    • TIL
    • Twitter threads
  • Books
  • Talks
  • Trainings
    • Advanced iteration
    • Python for scripting and automation
    • Rust for Python developers
  • Courses
  • About
Link blog

Rules for Writing Software Tutorials · Refactoring English

by Michael Lynch on 22-01-2025 19:12

In this article the author puts forward 16 rules for writing good software tutorials:

  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. Spare the reader from mindless tasks
  9. Keep your code in a working state
  10. Teach one thing
  11. Don’t try to look pretty
  12. Minimize dependencies
  13. Specify filenames clearly
  14. Use consistent, descriptive headings
  15. Demonstrate that your solution works
  16. Link to a complete example

All of these rules made perfect sense to me and some of them I already try to enforce in my articles. The suggestions that resonated particularly well with me were those related to making your tutorial as easily reproducible and as easy to follow along as possible. To this end, Michael suggests several tweaks I can make to my code samples that make life much easier for the reader, which should be my end goal any way.

I'm happy to say that I have already been doing things in this direction. For example, I used to include lots of snippets of Python REPL sessions, like this:

>>> x, y = 1, 2
>>> x
1
>>> y
2

However, this was hard to work with if you wanted to copy my code and run it yourself. A small change I made was to start writing everything as Python scripts and use the print function instead:

x, y = 1, 2
print(x)  # 1
print(y)  # 2

This is much easier to copy and run for yourself. Not to mention the “copy to clipboard” button I added to all code snippets!

Previous link Next link

Number 73 is a number packed with interesting properties.

mathspp
  • Blog
    • Pydon'ts
    • Problems
    • TIL
    • Twitter threads
  • Books
  • Talks
  • Trainings
    • Advanced iteration
    • Python for scripting and automation
    • Rust for Python developers
  • Courses
  • About