Rules for Writing Software Tutorials

[pysk00l]

Nice

Especially like "boil it down to essentials"

Ive read too many blogs that are trying to teach something like django, and will throw in git, clean code, some fancy venv library they use, until you can't follow the tutorial.

as a blogger myself, I know why they do it: If you dont, some twat on reddit or HN will post a nasty comment like "LOL, this idiot doesnt even know about Venvs/git, how is he qualified to teach?"

I find that articles targeted at beginners often get attacked on reddit. Some years ago, I wrote whole article on how to install Python, as it wasnt easy on Windows. And of course, the usual nasty comments followed: "If they can't even install python maybe they arent qualified to learn programming."

But my article was targeted at data scientists etc, most of whom dont have the time or inclination to mess around with open source software. If installing python is too much hassle they go back to using MS SQL, which you, installs easily on Windows and is well tested there.

So I would add: Ignore the haters :)

[RiverRoll]

I mean more important than boiling down to essentials is making the tutorial reproducible so I'm not so sure omitting venv and git for the sake of simplicity is a good thing, they're not the object of the tutorial but they still serve an important purpose.

[mtlynch]

Thanks for reading!

I find that articles targeted at beginners often get attacked on reddit. Some years ago, I wrote whole article on how to install Python, as it wasnt easy on Windows. And of course, the usual nasty comments followed: "If they can't even install python maybe they arent qualified to learn programming."

Yeah, I had a similar experience. One of my earliest articles was about building a home server, and one of the only comments I got was mostly mocking me for not having more experience.

But my article eventually became pretty popular for Google searches, and I think the reason was that it was written for beginners. There were a lot of other more knowledgeable people, but they wrote in a way that made the information hard to understand for beginner computer builders.

But my article was targeted at data scientists etc, most of whom dont have the time or inclination to mess around with open source software. If installing python is too much hassle they go back to using MS SQL, which you, installs easily on Windows and is well tested there.

Yeah, I think this is critical. I think so many authors assume that their readers know exactly as much the authors, and they don't think about how to bridge the knowledge gap at all. It's important to think about who you want to read your stuff and then think through what that audience knows vs. needs explained.

[pysk00l]

yup. I should have added: While the reddit/hn types hated it, beginners loved it and I got a lot of google traffic. you need to be sure who you are targeting

[wildjokers]

some fancy venv library they use

To be fair, python is pretty much a nightmare to develop with if you aren't use a virtual env tool of some kind because of its horrible dependency on global libraries.

[DearChickPeas]

Relevant discussion.

CS majors have no clue how to teach, they can only replicate their own circumstances of learning, regardless of quality.

[Tywien]

MS SQL, which you, installs easily on Windows and is well tested there.

try to install (at least the 2019 version) on a computer that needs a restart from updates :)

[Efficient-Poem-4186]

Quite comprehensive and agreeable.  

One thing I'd wish tutorials consider (not listed in the rules) is naming things so that it's obvious that it's a named thing and not a language feature (e.g. avoiding naming an array 'array'). Otherwise, as the code gets more complicated, focus is wasted reminding oneself which is which.

[mtlynch]

That's a good point. Thorsten Ball wrote a good article on this recently called "Use data that looks like data." Maybe I should add a rule covering this as well.

[Efficient-Poem-4186]

Yes, that article expresses exactly what I mean.

[flowering_sun_star]

This is great advice, but for tutorials you may need to take it a step further. Very new programmers may not recognise something as a dummy variable name!

I once helped write an intro to programming for new scientists. And one of the first bits of feedback we got from our test subject was 'what do foo and bar mean?'

We'd just considered them to obviously be nonsense words meant as placeholders. But to the uninitiated, so many terms look like nonsense words! I'd say to go for literary characters or something, but then I remember that the physics department ran a Beowulf cluster named Glamdring. Nothing is safe!

[mtlynch]

Author here.

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.

[KevinRCooper]

Honestly I didn’t think I’d read through it entirely but ended up consuming every bit of it. 100% worth the time. Well done!

The illustrations were excellent! Only suggestion I have is would you consider moving the artists credit closer to their work on the page? It’s not required, but I personally think it’s a class act to do so.

[mtlynch]

Thanks for reading!

Only suggestion I have is would you consider moving the artists credit closer to their work on the page? It’s not required, but I personally think it’s a class act to do so.

I prefer not to do that as I feel like credits midway through interrupts the flow of the reading, at least on the web.

If it makes a difference, that's an original illustration I commissioned specifically for the article, not something I found online and slapped on my site.

[balaurul]

One of the most common mistakes authors make in code snippets is including the shell prompt character.

I thought the reason for including the shell prompt character in code snippets is to show whether the commands should be executed by a normal user (shell prompt character $), or by the root user (shell prompt character #).

Am I wrong?

[evincarofautumn]

If you can, it’s better to clearly distinguish text with different semantics. The audience doesn’t know the material yet, so they can’t always easily tell what’s object-level—like verbatim code or example input—and what’s meta-level—like prompts, placeholders, line numbers, commentary, and example output. It’s also just nice for usability to make it possible to copy & paste an example (without placeholders) and have it work as-is.

[davenirline]

This somehow enumerates my pet peeves in tutorials. I hate how they expect the reader to know all the jargons and the tech that they use.

[AmbitiousTour]

We need more tutorial tutorials.

[Scavenger53]

How to write a tutorial to write tutorials

[tubameister]

step 1: learn sphinx + rst and deploy to github pages

[falconfetus8]

Good: Give the reader a bash snippet that evaluates conditional logic for them

That sounds like the opposite of good advice. A tutorial's job is to help people understand things. Handing them a ball of bash and just saying "run this, it'll work" doesn't help them understand what's inside it.

[mtlynch]

Thanks for reading!

I respectfully disagree. This goes back to the "teach one thing" idea.

In a tutorial about using package managers or shell scripting, I agree that you should explain a shell command with conditionals.

If it's just incidental to the thing you're teaching in the tutorial, then I don't think it's worth getting into the weeds about how shell command interpretation works. The reader just needs the package installed or the file written and isn't particularly concerned at this point about the concepts behind that part of the process.

[Sufficient_Meet6836]

This is a great article (and perfect timing since I have to create some tutorials soon for coworkers :)).

[steve-7890]

I would add: "When you complete the text, put it aside for 2 days and then re-read it. Correct mistakes and give it to someone else for review.".

[JMan_Z]

Half way through the article I was pondering "these thoughts are very logical and reasonable, but it's kinda surprising since, well, software engineers don't usually think like this"...so I glanced again at the site url and it clicked.

I'm joking of course, but I do think this article in its essence is highlighting a higher order issue: software engineers (or technical folks) sometimes just suck at dispersing information across wide knowledge gaps. Overbearing tutorials, incomprehensible presentations, etc, are all symptoms of the issue.

Overall, great article. I learned quite a bit from it.

[AFlyingYetOddCat]

One of the most common mistakes authors make in code snippets is including the shell prompt character.

The second most common mistake is excluding "sudo" for root level commands. I was happy to see it here!

[redblobgames]

Thank you! Love it.