I've been thinking for a long time about anti-patterns I see when following software tutorials, so I put together this list of things I think differentiate good tutorials from poor ones.
I'm happy to hear any feedback on this list or hear about other things I should include.
The article gives some useful tips. But (if I may) I'll disagree with a couple of small parts:
> Write for beginners
I prefer "write for your audience". For example, in the first lesson for my canvas library[1], I'm aiming at an audience of front-end developers - they should know how to code a very basic HTML page and start a local server to view it.
Of course, my lesson fails here. I'll add a line near the top of the copy to say who the intended audience is, and a link to the MDN frontend developer course[2] for any complete beginners who (somehow) found the lesson.
> Make code snippets copy/pasteable
Maybe I'm an outlier but, when I blindly copy-paste code, I rarely learn about that code: it's just some magic that I feed into the computer to get results. I learn better when the tutorial forces me to type out the code (and I do nasty things in my tutorial to persuade learners to type rather than copy-paste).
I am with you on #1 -- I write a lot of tutorials but I'm not trying to help you learn how to open a terminal. I'd prefer to lose those readers up front rather than frustrate them for 30 minutes.
#2 is too far. If people want to misuse your stuff, shame on them, but don't boobie trap it!
Yeah, I think I need a different wording for "write for beginners." It's not "write for beginners to programming" but "write for beginners to your particular subject."
Like in your case, you're writing for frontend developers who are not new to making webpages, but they're beginners at using the canvas element.
I don't expect authors to write a new tutorial whenever the syntax for doing something changes. But it would be unbelievably helpful if you could just stick a banner on the top of a piece saying "this doesn't work anymore" as soon as that's true (which, unfortunately, is usually about three months after you write it)
I have a minor nit to pick. I actually prefer when tutorials provide the prompts for all code snippets for two reasons:
1. Many tutorials reference many languages. (I frequently write tutorials for students that include bash, sql, and python.) Providing the prompts `$`, `sqlite>` and `>>>` makes it obvious which language a piece of code is being written in.
2. Certain types of code should not be thoughtlessly copy/pasted, and providing multiline `$` prompts enforce that the user copy/pastes line by line. A good example is a sequence of commands that involves `sudo dd` to format a harddrive. But for really intro-level stuff I want the student/reader to carefully think about all the commands, and forcing them to copy/paste line by line helps achieve that goal.
That said, this is an overall good introduction to writing that I will definitely making required reading for some of my data science students. When the book is complete, I'll be happily buying a copy :)
> Certain types of code should not be thoughtlessly copy/pasted, and providing multiline `$` prompts enforce that the user copy/pastes line by line.
I hardcore oppose this kind of thing, for the same reason I oppose people putting obstacles in the way of curl-to-bash.
Adding the prompt character doesn’t make people think, it just makes people press backspace. Frequently I’m reading a tutorial because I’m trying to assemble headless scripts for setting up a VM and I really just need verbatim lines I can copy/paste so I know I’ve got the right arguments.
>Many tutorials reference many languages. (I frequently write tutorials for students that include bash, sql, and python.) Providing the prompts `$`, `sqlite>` and `>>>` makes it obvious which language a piece of code is being written in.
I think it's fine to show the prompt character, but I think it's the author's job to make sure that copy/paste still works. I've seen a lot of examples that use CSS to show the prompt or line number without it becoming part of copied text, and I'm highly in favor of that.
I think if I had to choose between breaking copy/paste and making the language obvious with the prompt character, I'd exclude the prompt, but I think that's a matter of taste.
>Certain types of code should not be thoughtlessly copy/pasted, and providing multiline `$` prompts enforce that the user copy/pastes line by line. A good example is a sequence of commands that involves `sudo dd` to format a harddrive. But for really intro-level stuff I want the student/reader to carefully think about all the commands, and forcing them to copy/paste line by line helps achieve that goal.
Yeah, I agree about preventing the reader from copy/pasting something dangerous.
In tutorials that require a reboot, I'll never include a reboot command bunched in with other commands because I don't want the user to do it by mistake. And I agree for something like `dd`, you'd want to present it in a way to make it hard for the reader to make mistakes or run it thoughtlessly.
I'm not sure about that. There are markdown rendering engines where you can specify the language of a codeblock and it will render with specific CSS based on the language. So you can do something like ```bash ... ``` and it will show the code with newlines prefixed by "$"
AFAIK specifying a language only makes a difference for syntax highlighting. I have never seen a markdown processor that would add prompts to the code based on the specified language.
Syntax highlighting is just CSS. There's nothing stopping you from adding your own custom CSS to the code block which will prefix lines with the prompts.
This advice reminds me of my list of rules for technical presentations. One of which is no live coding. Record your live coding if you need it. Live coding serves no one, and if you record it, it's there and it works.
I do not know of a case where a recording is not better.
"Oh, but what if you have to update what you do"
Then when you practice it for your presentation, record it and put that in.
"Oh, but I don't want to edit the video"
If you have to edit the video to take out the useless parts, you are just leaving the useless parts in during the live coding.
"Oh, but I enjoy it"
The presentation is for the audience.
"What if they ask a question"
If they ask a question about what you did, you can easily replay it.
If they ask a question beyond that, you can also dive into live coding, but that's the exception.
Really good advice there. Thank you for writing this.
I've written several in-house tutorials to our internal product, and I've come to internalize your advice somehow.
IMO it's mostly about empathy. I remember myself as a newbie perplexed by this product and try to write to my younger self. I also make a point to always spend a lot of time with new hires and get their feedback and their viewpoint.
Sometimes this advice of describing what something is and why you'd use it is helpful. Other times I already know what it's for and just want to use it, and don't like having to slog through descriptions that don't help with implementation. There is no universal right or wrong answer here, since it will depend on who is reading your tutorial, what their level of expertise is, and what they need.
A tutorial can provide the best of both worlds by putting the background stuff of each section in a sidebar, so the reader can easily skip it or delve more deeply if they wish.
I actually don’t like the example with Djano and JS: too much bad/fake SEO compounded by Googles enshitification mean that very specific search terms for specific technologies get drowned out by generic word salads like “organising and structuring djano projects”.
Yeah, I see what you're saying. I had this article[0] in mind, which is a well-written article and ranks #1 for "organize front end code django" on Google. None of the other results are close in relevance or quality.
But I guess that example could be confusing for readers who aren't familiar enough with Django to know why structuring the frontend is a hard problem that not many people write about.
I've been thinking for a long time about anti-patterns I see when following software tutorials, so I put together this list of things I think differentiate good tutorials from poor ones.
I'm happy to hear any feedback on this list or hear about other things I should include.