I hope that plenty of developers read this, especially folks on open source projects who don't have dedicated documentation people. There's so much bad documentation out there, and many of these tips are key.
A couple more of my own:
TEST YOUR DOCS
As @codetrotter suggests in another comment, run through your own tutorial with a fresh VM and follow it closely; you'll almost certainly find something to improve.
But this works better if you have someone else try it out instead: get on a video call with them, have them share their screen and speak their thoughts out loud, and most importantly, don't help them. You're trying to find out if they can complete this without additional help. (Yes, it's a usability test.)
BETTER SOFTWARE MAKES SIMPLER TUTORIALS
The article's rule about "let computers evaluate conditional logic" is a good one, but there are multiple places to fix that problem. Sometimes it's in the tutorial, sometimes it's in the software product itself. When the tutorial makes the reader do complex work, it may be a sign that the software has UX issues. You may not be in a position to fix it, but you can probably file an issue.
For the example in the article: could you make the same package name work on all three Debian versions? It'd certainly improve the user experience, and probably make the installation process more resilient.
I spend a great deal of time, testing the hell out of my supporting material.
I usually supply a GitHub repo or gist, with either a full app, or a playground. In many cases, I’ll have a full app, already running, with just one source file, that we’ll be modifying. This may be in a tagged GitHub repository or gist, with tags, denoting steps[0]. In other cases, I’ll supply a zip file, with everything in it[1].
I can take a month, developing a tutorial that can be run in an hour.
Teaching is hard. A good trainer spends many hours, preparing for relatively short classes. It’s sort of like playing a concert; you only get one chance, so preparation is key. Also, in tech, the students are often more accomplished than the teacher. It can be a tough room.
That said, I have attended some valuable tutorials, in which the teacher did a terrible job, preparing. It’s just that I don’t work that way, myself.
The main reason that I write tutorials, is to teach myself. I don’t think anyone else really pays much attention to my work[2]. I have presented a few “official” classes[1], but mostly, I work on my own. I have, actually, been teaching for decades, in small, short, seminar form; mostly for non-technical stuff.
> But this works better if you have someone else try it out instead
1000x yes.
Yoz, you are wise and while what you say may seem like an obvious thing, it isn't. I was once in the unfortunate position of having to write manuals for software I did not design, so I went through it thinking I was the "average user." As it turns out, I was under the false impression that my documentation was perfectly understandable to anyone, to the point where they could sit down, rtfm and go.
Boy was I wrong.
I later got into an area of work where I had to help individuals with cognitive disabilities adapt to new workflows in factory settings. One of the exercises I had to do to earn my certification in this field was to imagine an individual that had never seen a broom or dustpan before, then use only photos to explain how to sweep a floor. It's far more challenging than you think. I realized that not only was I making the mistake of explaining things to myself, but I was also assuming that I could put myself in someone else's shoes and interpret my own instructions with fresh eyes. This, as it turns it, was folly.
That experience propelled my documentation forward by leaps and bounds, though. In my current position, I came up with over a dozen single-page instructions to resolve issues customers were having with our products that, previous to my working here, generally took an hour-long phone call, eating up time and resources on both ends. Each page was tested with a coworker or willing customer that had never worked with the product before with welcomed feedback. The result was a significant drop in time wasted on these otherwise simple fixes, allowing us to redirect our big guns at the more complex issues that arise.
For anyone interested in the kinds of pitfalls we fall into when we think we can bridge the gap between two minds with our "exact" instructions, check out this video. I think it does a wonderful job of conveying these problems in communication in a really fun way.
> But this works better if you have someone else try it out instead: get on a video call with them, have them share their screen and speak their thoughts out loud, and most importantly, don't help them. You're trying to find out if they can complete this without additional help. (Yes, it's a usability test.)
If you take _nothing_ else away from the article and/or this thread, take this away!
I pride myself on the quality of docs that I produce and my "secret" is enlisting guinea pigs. Before linking somebody to the doc(s) they need, I'll send them a message akin to "if you get stuck at literally any point or encounter literally any error or shell output that does not match what's in the docs, stop and message me. We'll work it out together and the docs will be better for the next person"
Do that a few times and you have a high-quality document that'll cover the process and any known edge cases.
The critical bit is that the person that needs the doc is already not having an awesome day; make it clear to them that you're here to help and not in a "come to me after you've spent 2 hours trying to make it work" way.
A couple more of my own:
TEST YOUR DOCS
As @codetrotter suggests in another comment, run through your own tutorial with a fresh VM and follow it closely; you'll almost certainly find something to improve.
But this works better if you have someone else try it out instead: get on a video call with them, have them share their screen and speak their thoughts out loud, and most importantly, don't help them. You're trying to find out if they can complete this without additional help. (Yes, it's a usability test.)
BETTER SOFTWARE MAKES SIMPLER TUTORIALS
The article's rule about "let computers evaluate conditional logic" is a good one, but there are multiple places to fix that problem. Sometimes it's in the tutorial, sometimes it's in the software product itself. When the tutorial makes the reader do complex work, it may be a sign that the software has UX issues. You may not be in a position to fix it, but you can probably file an issue.
For the example in the article: could you make the same package name work on all three Debian versions? It'd certainly improve the user experience, and probably make the installation process more resilient.