6 ms·

Rules for writing software tutorials

376 points by mtlynch 2y ago

mtlynch 2y ago
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.
- MortyWaves 2y ago
  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”. There’s probably a million of those already.
  - mtlynch 2y ago
    Thanks for reading and for the feedback. 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. [0] https://www.saaspegasus.com/guides/modern-javascript-for-django-developers/client-server-architectures/ https://www.saaspegasus.com/guides/modern-javascript-for-dja...
- jackpirate 2y ago
  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 :)
  - mtlynch 2y ago
    Thanks for reading! >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.
    - jackpirate 2y ago
      > 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. This is unfortunately not compatible with writing the tutorial in markdown to be rendered on github.
      - xmprt 2y ago
        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 "$"
        2y ago
- olvy0 2y ago
  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.
- rikroots 2y ago
  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). [1] - https://scrawl-v8.rikweb.org.uk/learn/first-lesson https://scrawl-v8.rikweb.org.uk/learn/first-lesson [2] - https://developer.mozilla.org/en-US/docs/Learn_web_development https://developer.mozilla.org/en-US/docs/Learn_web_developme...
  - pwillia7 2y ago
    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!
  - mtlynch 2y ago
    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.
    - jlizen 2y ago
      Maybe, don't assume familiarity?
- bandrami 2y ago
  My main request, which I know is a big ask: Actively deprecate. 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)
  - deleted 2y ago
    [deleted]
- jasonlotito 2y ago
  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.
- kmoser 2y ago
  https://refactoringenglish.com/chapters/rules-for-software-tutorials/#an-introduction-to-docker-containers https://refactoringenglish.com/chapters/rules-for-software-t... 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.
deleted 2y ago
[deleted]
ctkhn 2y ago
Very good stuff. Going to consult this as I build personal and work projects. Working at a huge org right now and its amazing how many crucial details are missed in the tutorials that we have for internal things we depend on
indentit 2y ago
I really like how clear and well laid out these rules are. It covers lots of things that I have always thought about when I write instructions in README files etc, so it's very nice to see everything neatly described/reasoned in one place. Thanks for sharing!
alentred 2y ago
Extending on the copy-pasteable snippets, another big improvement (flaw to avoid) is to include all imports to the code snippets.
- BiteCode_dev 2y ago
  And the names of packages to install. Don't assume the imports match it. Check.
stared 2y ago
There is a lot of good advice about details! Especially one that got my heart: > Some authors design their tutorials the way you’d give instructions for an origami structure. It’s a mysterious sequence of twists and folds until you get to the end, and then: wow, it’s a beautiful swan! > A grand finale might be fun for origami, but it’s stressful for the reader." Yes, a lot of tutorials are puzzle games. You need to guess other tools to install, which are obvious to the author, but not everyone. I would add a few things: * Have two types of examples - minimal and the most typical (one is to show the essence without distraction, the second to serve as a practical starting point) * Always provide the full code sequence to run code; if there are any assumptions, these should be listed explicitly (e.g. "it needs Node 22"); you hinted a bit, but since many tutorials miss that, it deserves attention. Even better, if it is possible to combine it into one point and make it runnable. For example, for a package I had been developing, livelossplot, I made Jupyter Notebooks runnable in Colab: * https://colab.research.google.com/github/stared/livelossplot/blob/master/examples/minimal.ipynb https://colab.research.google.com/github/stared/livelossplot... * https://colab.research.google.com/github/stared/livelossplot/blob/master/examples/pytorch.ipynb https://colab.research.google.com/github/stared/livelossplot...
- jasonjmcghee 2y ago
  This is something that resonates / I really strive for. Cutting corners / over simplifying intentionally to have a "working" (poor) usable step along the way, that you can then improve / fix and explain why you can't / shouldn't cut those corners. Not applicable to all tutorials, but I like this approach because it feels more like an exploratory learning experience rather than prescriptive instruction.
jagged-chisel 2y ago
I thought "Keep your code in a working state" would be discussing how to keep code working when some dependency changes. What was covered is valuable advice, but I'd like some exploration on keeping the published code cohesive under refactoring and refinement away from the text. For example, if I'm P. Shirley and I've written a book (with code) about following light rays between a virtual camera and virtual objects. I have refactored some code to be more clear. Of course, I have iterated on this code to verify it remains correct, but the related text isn't affected. I have to remember where to paste this new code. Unless the documentation had some kind of reference to the specific file, lines, and/or function to render into the text. What's the advice for best practices here?
- amenghra 2y ago
  Some people embed code in a way that’s similar to a test and then have a process to run/test all the embedded code.
- smitty1e 2y ago
  Given that most examples are relatives small, one could leverage org-babel[1] and write the tutorial with executable code, and go straight to .PDF! [1] https://org-babel.readthedocs.io/en/latest/ https://org-babel.readthedocs.io/en/latest/
- joshka 2y ago
  Make the tutorial text include the code verbatim from a working repo that passes CI. No pasting necessary. Sure you still have to verify that the tutorial text aligns with the code changes, but you don't have to do anything manual to update the code in the tutorial. As an actual example of this, here's a plugin for Remark that allows us to import specific functions from a rust source file. https://github.com/ratatui/ratatui-website/blob/main/src/plugins/remark-code-import.ts https://github.com/ratatui/ratatui-website/blob/main/src/plu... If the source code fails to compile, we get a CI error (in the rust checks). If the source code changes in a way where the import is no longer correct, we get a CI error (in the npm checks).
- KittyCatCuddler 2y ago
  I've actually contributed to the Ray Tracing In one Weekend project. The process is pretty manual. The book is actually written HTML, and the code snippets are duplicated from the source (not linked in). Before release, it's a manual process to go through each book and read/build it from scratch. In my opinion, the open source nature really is the key thing here. Most of the issues are small things (typos, confusing verbage, etc). So it get's refined as people read it.
rinvi 2y ago
Thank you for this. I want to also reference diataxis [0], a systematic approach to technical documentation authoring, which I think has some good advice on the subject of tutorials. [0] https://diataxis.fr/tutorials/ https://diataxis.fr/tutorials/
rglover 2y ago
This is a great list of stuff. I spent years writing tutorials and wish this list existed when I first started.
edihasaj 2y ago
Great
Linux-Fan 2y ago
I am rather ambivalent about these rules. I disagree with a lot of the individual points, but I am also sure that I have probably often written bad tutorials myself where some of the rules would have clearly helped... :) > 5. Make code snippets copy/pasteable I like to use the prompt to identify the language and also the user (root `#` vs. user shell `$`) to perform the action under. I advise against copying random commands off the internet especially those that run as root and may break your system (like `apt` and `--yes` together...). Of course, today, it is often assumed that you have sudo setup and then `sudo ...` is used to indicate the use of root privileges. It is an interesting convention although in my opinion this sometimes hides the actual intent. I prefer: # echo 3 > /proc/sys/vm/drop_caches over echo 3 | sudo tee /proc/sys/vm/drop_caches The example given in the article is exactly one where attention is required: It adds a PPA as root, thereby giving "full control" to the PPA author. Never straightout copy-paste such stuff. > 6. Use long versions of command-line flags I am so much more used to the short versions hence I prefer `grep -RF` over `grep --dereference-recursive --fixed-strings`. Also, my go-to documentation about these commands (POSIX) doesn't even know about the long options. I know that the advice to prefer the long options is repeated pretty often so it might just be me :) > 7. Separate user-defined values from reusable logic Ever followed some "enterprise-grade" software setup tutorial? Sometimes they start by assigning 20 variables to some generic values that you don't change most of the time and then go about to reference them on the next 20 pages or such making it close to impossible to know what is really going on. Also I find that for simple cases this greatly complicates the input process. I think the example doesn't really show the difference because it has some variables (just not in shell syntax) in the code already like `YOUR-API-TOKEN`. Of course it is better to write `$API_TOKEN` rather than `YOUR-API-TOKEN`. I often prefer to see the example value in the example i.e. not `YOUR-API-TOKEN` but some real string (if feasible). In many cases I won't change a value in the beginning to see how far I get with a “known valid input”. Also, I often prefer to pattern-match some real value against what I have available, e.g. I have a key which I think could be the API key but if the format is totally different from the tutorial I may realize that this is an "app token" rather than "API key" and that I may need to get a different value if it fails to run with my input or such. > 9. Let computers evaluate conditional logic If dosed correctly, I think this is good advice. I'd strongly prefer the conditional boxes from the “bad” example over the “good” monster shell script command. In my opinion a tutorial shouldn't optimize for speed of execution but rather foster the understanding by the reader. There is no help if I find this post 10 years later and it helpfully outputs “ERROR: Unsupported platform” on my Debian 16 system. If the text instructions are given as in the “bad” example, I quickly realize that all of this is outdated and I should probably try with the most recent package name (example-package2) rather than meddle with some script.
baudaux 2y ago
> As soon as possible, show a working demo or screenshot of what the reader will create by the end of your tutorial. For this reason I am building a new way of writing coding tutorials, with the possibility of writing and running code snippets into the web browser including graphical apps: https://exalib.com https://exalib.com
- neochief 2y ago
  I get SSL handshake error from cloudflare when I try to visit that URL.
codetrotter 2y ago
> Tutorials often forget to mention some key detail, preventing readers from replicating the author’s process. I also find this sometimes. A high quality tutorial on the other hand, is often one where the author bothered to set up a fresh VM and follow their own guide step by step to confirm that everything works as described. This way the author avoids unintentionally forgetting to mention additional dependencies that have to be installed and additional config files that need to be tweaked in order for the steps to work.
BiteCode_dev 2y ago
Lot of good advice. I'll nitpick a bit. You can't tell your user to "echo 'awesomecopter' | sudo tee /etc/hostname" if you may have windows users. And even for purely linux user, "Good: Give the reader a bash snippet that evaluates conditional logic for them" is quite a scary wall of code for a beginner that as no idea why copy/paste that. All in all, don't confuse "giving the shortest path to a working solution" and "teaching", which both can be in a tutorial, but they have different goals and you should choose accordingly. I think the "Teach one thing" is probably the best advice in the article, and too often ignored. I remember as a kid reading Swinnen's book to learn Python and having to understand OOP with his example using ions was a terrible experience. And if you think "well you should have known that, they teach it in school", you are missing the point. That being said, writing an excellent tutorial takes a lot of work. Way more than a good-enough one. Choose wisely.
- runevault 2y ago
  I really wish more tutorial makers would do the "teach one thing". Like I dabble in gamedev, and most people who create content for it generate 45 minute to many hour long tutorials that are end to end, instead of teaching "this is how you deal with navigation" "this is how you handle movement" etc. Means people who want to learn stuff are stuck interacting with a massive block of stuff which makes extricating out the part they need and planting it in their own project wildly harder.
  - BiteCode_dev 2y ago
    Yes, and then link this things to pre-requisite, and show how several of those one-things come together in a separate piece. But again, it's a LOT of work to do that. E.G: To write "https://www.bitecode.dev/p/back-to-basics-with-pip-and-venv https://www.bitecode.dev/p/back-to-basics-with-pip-and-venv", I need to be able to rely on "https://www.bitecode.dev/p/installing-python-the-bare-minimum https://www.bitecode.dev/p/installing-python-the-bare-minimu..." which in turn needs to rely on "https://www.bitecode.dev/p/ultra-beginners-first-steps-for-the https://www.bitecode.dev/p/ultra-beginners-first-steps-for-t...". That's almost 9000 words, or 10% of the average novel size just to give beginners a good chance of success on one single topic. Between doc, tutorials, FOSS and forums, the entire software industry is just standing on a gigantic pile of billions of hours of free labor.
yoz 2y ago
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.
- __mharrison__ 2y ago
  I often use doctest to ensure my books "compile". Students hate it when your code doesn't work.
- ChrisMarshallNY 2y ago
  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. [0] https://github.com/LittleGreenViper/DemoCustomChartApp/tags https://github.com/LittleGreenViper/DemoCustomChartApp/tags [1] https://github.com/ChrisMarshallNY/ITCB-master https://github.com/ChrisMarshallNY/ITCB-master [2] https://littlegreenviper.com/miscellany/ https://littlegreenviper.com/miscellany/ (not every series is a tutorial).
jen20 2y ago
My pet peeve is code along the lines of: if err != nil { // handle errors } Or: try { // something that can fail } catch (Exception e) { // handle exceptions here } It's usually laziness from the author, but not stating _what types_ of error may occur and how should typically handle them is a plague on documentation and tutorials.
deleted 2y ago
[deleted]
lincpa 2y ago
[dead]
chocoboaus2 2y ago
This is REALLY good.
tolciho 2y ago
> Make code snippets copy/pasteable Naw, copying and pasting won't develop touch typing nor muscle memory skills. The prompt is sort of a context indicator for the command, as other comments indicate. Also if you're using one of those horrid browsers with CSS support who knows if there are characters that do not display but are included in what is copied. Security risk? Well, you started a chonky browser with a bad security record, so uh additional security risk. Also they probably should be able to type out the commands by hand at the speed of thought, or the commands should be put into a Makefile or script or done via configuration management. Making it easy to copy and paste? Well, if you want to train people to mindlessly copy-n-paste who knows what to who knows where, I guess. Doesn't sound like that would train people to engage deeply with the material. If there's a bigger code example I just put a "=> foo.lisp" link '(this is for Gemini (no, not the Google whatever nonesense (McCarthy invented AI to get money)), the modern web being too much yuck these days) so they can download the whole file. > Use long versions of command-line flags What are these? I'm on OpenBSD. More seriously, long flags may or may not help±quick! what does --fake-super for rsync(1) do?—and taking a peek into the manual (another reason I'm on OpenBSD) is sort of a spaced repetition to refresh you on what the flag does, and maybe to scan the list of options to see if anything new jumps out at you (or, at a certain age, what you've forgotten). Close engagement with the material (howeversomuch the learner hates this, as such brain exercise uses up precious energy) is probably a good thing. (Yes, I know that OpenBSD supports but generally does not document various wacky --from-backside-of-gnu flags.) > Teach one thing I am too fond of puns (and have ulterior motives, given the excess of car sitting in America, and the consequent loss of blood to the brain) to apply this in any meaningful way.
Fr3dd1 2y ago
For that topic some nice additional stuff: https://diataxis.fr/ https://diataxis.fr/
- remoquete 2y ago
  Diataxis gets often linked around here. It's simple, but by no means the solution to great docs. For more info, see https://idratherbewriting.com/blog/what-is-diataxis-documentation-framework https://idratherbewriting.com/blog/what-is-diataxis-document...
mongol 2y ago
What do you think about writing a tutorial without explaining terminology, but then ask an LLM to generate some kind of terminology index that shows at hover over the terms? If I am writing a tutorial it will take me much longer to explain terminology that I assume is known before. I can see the author's points, but all things considered if I am writing "for free" I don't want to spend unneccessary time. Letting the tutorial be my words, and the terminology index be that of an LLM may be a good balance?
- supriyo-biswas 2y ago
  This is similar to Msty's[1] "Delvify" feature that generates links for keywords in a given text, with the ability to "delve" into each highlighted topic. While I'm unfamiliar with how it's implemented there, I can certainly see this working with multiple rounds of prompting, and possibly some external data sources and human curation to ensure that the terminology index is actually useful to readers. [1] https://msty.app/ https://msty.app/
cloogshicer 2y ago
Fantastic article.
ChrisMarshallNY 2y ago
Thanks for posting this. It’s an excellent example of clear, useful writing, about a topic that could use all the help it can get.
laurentlb 2y ago
A good tutorial should be reviewed and tested by a second person.
bandrami 2y ago
Let me add: Specify up front date and software version. I can't stress this enough. As the CADT release cycle becomes ubiquitous we're approaching a situation where many tutorials are outdated by the time you finish them.
- tommica 2y ago
  What is CADT? Computer-Aided Design and Testing?
  - bandrami 2y ago
    Sorry, I didn't realize that abbreviation had lost currency. Cascade of Attention Deficit Teenagers https://www.jwz.org/doc/cadt.html https://www.jwz.org/doc/cadt.html
    - cookie_monsta 2y ago
      Maybe because it never had currency?
      - bandrami 2y ago
        It absolutely did. It was even part of the Init Wars (prayers, sorrows)
nemetroid 2y ago
I think many of these rules are good, but that there's a too strong focus on ensuring that shell snippets are copy-pasteable without inspection. This comes at the detriment of other considerations, and I think some of the advice goes too far. Especially so when it comes to the different package names on different Debian versions: what originally was a oneliner is now fifteen lines long with six different branches. What should the reader do if the copy-pasted code fails? How do they know which part failed? What is an "/etc/os-release"? Yes, the happy path becomes simpler, but the reader will struggle to recover from any errors.
taeric 2y ago
If you haven't, I highly recommend taking a look at Knuth's manuals. Even if you are completely uninterested in METAFONT or TeX, they are a delight to read and I would hold both up as a very good aspirational target for software manuals.
wiradikusuma 2y ago
For those who can't find other people as your guinea pig, this is the trick I use: After finishing your tutorial, just wait for a few days, and try following it yourself, in a fresh env. I'm cursed (blessed?) with fish memory so after a few days I forgot everything I wrote.
javier_e06 2y ago
I thought that using Makefile targets was the shortest friendliest to show what a project can do. Turns out make and Makefiles can be mysterious when they fail. Tutorials are "best-effort" and often don't dwell on the rabbit-holes they create when a poor soul runs astray of the sunny path. Example of a good tutorial: Python's powerline shell: https://github.com/b-ryan/powerline-shell https://github.com/b-ryan/powerline-shell The README is succinct. Well put together.
ozim 2y ago
A developer who’s new to the React web framework won’t understand terms like “JSX transpilation” or “reconciliation engine.” They probably also won’t understand “SPA,” “soft reload,” or “virtual DOM” unless they’ve worked with other JavaScript frameworks. Unfortunately if you don’t use that, your beginners will have hard time to believe you are “guru” that they seek. Like if they find other guys tutorial with fancy words they will flock there - looking for some magic trick or some revelation that will hopefully come down on them while reading bunch of hard words without understanding. Most tutorials are like that for this reason. If you want to teach people author is right - if you are cynical and just want to earn money on a tutorial that’s a different thing. One upside - people quitting “hard” course most likely will be embarrassed to ask for return of money as they would feel it is their fault they did not learn as topic is hard. If they feel topic was easy and they did not learn, that’s probably guy making tutorial not knowing enough. My cynical take :)
egberts1 2y ago
Look at all the US Army training movies from the 1950s. Those are near perfect.l tutorial.
uvtc 2y ago
A rule I try to follow: don't waste your reader's time.
lsofzz 2y ago
Thank you.
tdehnke 2y ago
Love it - I'd add to ensure you clearly specify what version numbers you are writing for, and include a date of your writing. Things change a lot between Version 3 and 6 of something, and something written 5 years ago may no longer apply or be valid today.

376 points by mtlynch 2y ago

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.

MortyWaves 2y ago
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”. There’s probably a million of those already.
- mtlynch 2y ago
  Thanks for reading and for the feedback. 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. [0] https://www.saaspegasus.com/guides/modern-javascript-for-django-developers/client-server-architectures/ https://www.saaspegasus.com/guides/modern-javascript-for-dja...
jackpirate 2y ago
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 :)
- mtlynch 2y ago
  Thanks for reading! >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.
  - jackpirate 2y ago
    > 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. This is unfortunately not compatible with writing the tutorial in markdown to be rendered on github.
    - xmprt 2y ago
      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 "$"
      - 2y ago
olvy0 2y ago
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.
rikroots 2y ago
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). [1] - https://scrawl-v8.rikweb.org.uk/learn/first-lesson https://scrawl-v8.rikweb.org.uk/learn/first-lesson [2] - https://developer.mozilla.org/en-US/docs/Learn_web_development https://developer.mozilla.org/en-US/docs/Learn_web_developme...
- pwillia7 2y ago
  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!
- mtlynch 2y ago
  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.
  - jlizen 2y ago
    Maybe, don't assume familiarity?
bandrami 2y ago
My main request, which I know is a big ask: Actively deprecate. 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)
- deleted 2y ago
  [deleted]
jasonlotito 2y ago
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.
kmoser 2y ago
https://refactoringenglish.com/chapters/rules-for-software-tutorials/#an-introduction-to-docker-containers https://refactoringenglish.com/chapters/rules-for-software-t... 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.

deleted 2y ago

[deleted]

ctkhn 2y ago

Very good stuff. Going to consult this as I build personal and work projects. Working at a huge org right now and its amazing how many crucial details are missed in the tutorials that we have for internal things we depend on

indentit 2y ago

I really like how clear and well laid out these rules are. It covers lots of things that I have always thought about when I write instructions in README files etc, so it's very nice to see everything neatly described/reasoned in one place. Thanks for sharing!

alentred 2y ago

Extending on the copy-pasteable snippets, another big improvement (flaw to avoid) is to include all imports to the code snippets.

BiteCode_dev 2y ago
And the names of packages to install. Don't assume the imports match it. Check.

stared 2y ago

There is a lot of good advice about details! Especially one that got my heart: > Some authors design their tutorials the way you’d give instructions for an origami structure. It’s a mysterious sequence of twists and folds until you get to the end, and then: wow, it’s a beautiful swan! > A grand finale might be fun for origami, but it’s stressful for the reader." Yes, a lot of tutorials are puzzle games. You need to guess other tools to install, which are obvious to the author, but not everyone. I would add a few things: * Have two types of examples - minimal and the most typical (one is to show the essence without distraction, the second to serve as a practical starting point) * Always provide the full code sequence to run code; if there are any assumptions, these should be listed explicitly (e.g. "it needs Node 22"); you hinted a bit, but since many tutorials miss that, it deserves attention. Even better, if it is possible to combine it into one point and make it runnable. For example, for a package I had been developing, livelossplot, I made Jupyter Notebooks runnable in Colab: * https://colab.research.google.com/github/stared/livelossplot/blob/master/examples/minimal.ipynb https://colab.research.google.com/github/stared/livelossplot... * https://colab.research.google.com/github/stared/livelossplot/blob/master/examples/pytorch.ipynb https://colab.research.google.com/github/stared/livelossplot...

jasonjmcghee 2y ago
This is something that resonates / I really strive for. Cutting corners / over simplifying intentionally to have a "working" (poor) usable step along the way, that you can then improve / fix and explain why you can't / shouldn't cut those corners. Not applicable to all tutorials, but I like this approach because it feels more like an exploratory learning experience rather than prescriptive instruction.

jagged-chisel 2y ago

I thought "Keep your code in a working state" would be discussing how to keep code working when some dependency changes. What was covered is valuable advice, but I'd like some exploration on keeping the published code cohesive under refactoring and refinement away from the text. For example, if I'm P. Shirley and I've written a book (with code) about following light rays between a virtual camera and virtual objects. I have refactored some code to be more clear. Of course, I have iterated on this code to verify it remains correct, but the related text isn't affected. I have to remember where to paste this new code. Unless the documentation had some kind of reference to the specific file, lines, and/or function to render into the text. What's the advice for best practices here?

amenghra 2y ago
Some people embed code in a way that’s similar to a test and then have a process to run/test all the embedded code.
smitty1e 2y ago
Given that most examples are relatives small, one could leverage org-babel[1] and write the tutorial with executable code, and go straight to .PDF! [1] https://org-babel.readthedocs.io/en/latest/ https://org-babel.readthedocs.io/en/latest/
joshka 2y ago
Make the tutorial text include the code verbatim from a working repo that passes CI. No pasting necessary. Sure you still have to verify that the tutorial text aligns with the code changes, but you don't have to do anything manual to update the code in the tutorial. As an actual example of this, here's a plugin for Remark that allows us to import specific functions from a rust source file. https://github.com/ratatui/ratatui-website/blob/main/src/plugins/remark-code-import.ts https://github.com/ratatui/ratatui-website/blob/main/src/plu... If the source code fails to compile, we get a CI error (in the rust checks). If the source code changes in a way where the import is no longer correct, we get a CI error (in the npm checks).
KittyCatCuddler 2y ago
I've actually contributed to the Ray Tracing In one Weekend project. The process is pretty manual. The book is actually written HTML, and the code snippets are duplicated from the source (not linked in). Before release, it's a manual process to go through each book and read/build it from scratch. In my opinion, the open source nature really is the key thing here. Most of the issues are small things (typos, confusing verbage, etc). So it get's refined as people read it.

rinvi 2y ago

Thank you for this. I want to also reference diataxis [0], a systematic approach to technical documentation authoring, which I think has some good advice on the subject of tutorials. [0] https://diataxis.fr/tutorials/ https://diataxis.fr/tutorials/

rglover 2y ago

This is a great list of stuff. I spent years writing tutorials and wish this list existed when I first started.

edihasaj 2y ago

Great

Linux-Fan 2y ago

I am rather ambivalent about these rules. I disagree with a lot of the individual points, but I am also sure that I have probably often written bad tutorials myself where some of the rules would have clearly helped... :) > 5. Make code snippets copy/pasteable I like to use the prompt to identify the language and also the user (root `#` vs. user shell `$`) to perform the action under. I advise against copying random commands off the internet especially those that run as root and may break your system (like `apt` and `--yes` together...). Of course, today, it is often assumed that you have sudo setup and then `sudo ...` is used to indicate the use of root privileges. It is an interesting convention although in my opinion this sometimes hides the actual intent. I prefer: # echo 3 > /proc/sys/vm/drop_caches over echo 3 | sudo tee /proc/sys/vm/drop_caches The example given in the article is exactly one where attention is required: It adds a PPA as root, thereby giving "full control" to the PPA author. Never straightout copy-paste such stuff. > 6. Use long versions of command-line flags I am so much more used to the short versions hence I prefer `grep -RF` over `grep --dereference-recursive --fixed-strings`. Also, my go-to documentation about these commands (POSIX) doesn't even know about the long options. I know that the advice to prefer the long options is repeated pretty often so it might just be me :) > 7. Separate user-defined values from reusable logic Ever followed some "enterprise-grade" software setup tutorial? Sometimes they start by assigning 20 variables to some generic values that you don't change most of the time and then go about to reference them on the next 20 pages or such making it close to impossible to know what is really going on. Also I find that for simple cases this greatly complicates the input process. I think the example doesn't really show the difference because it has some variables (just not in shell syntax) in the code already like `YOUR-API-TOKEN`. Of course it is better to write `$API_TOKEN` rather than `YOUR-API-TOKEN`. I often prefer to see the example value in the example i.e. not `YOUR-API-TOKEN` but some real string (if feasible). In many cases I won't change a value in the beginning to see how far I get with a “known valid input”. Also, I often prefer to pattern-match some real value against what I have available, e.g. I have a key which I think could be the API key but if the format is totally different from the tutorial I may realize that this is an "app token" rather than "API key" and that I may need to get a different value if it fails to run with my input or such. > 9. Let computers evaluate conditional logic If dosed correctly, I think this is good advice. I'd strongly prefer the conditional boxes from the “bad” example over the “good” monster shell script command. In my opinion a tutorial shouldn't optimize for speed of execution but rather foster the understanding by the reader. There is no help if I find this post 10 years later and it helpfully outputs “ERROR: Unsupported platform” on my Debian 16 system. If the text instructions are given as in the “bad” example, I quickly realize that all of this is outdated and I should probably try with the most recent package name (example-package2) rather than meddle with some script.

baudaux 2y ago

> As soon as possible, show a working demo or screenshot of what the reader will create by the end of your tutorial. For this reason I am building a new way of writing coding tutorials, with the possibility of writing and running code snippets into the web browser including graphical apps: https://exalib.com https://exalib.com

neochief 2y ago
I get SSL handshake error from cloudflare when I try to visit that URL.

codetrotter 2y ago

> Tutorials often forget to mention some key detail, preventing readers from replicating the author’s process. I also find this sometimes. A high quality tutorial on the other hand, is often one where the author bothered to set up a fresh VM and follow their own guide step by step to confirm that everything works as described. This way the author avoids unintentionally forgetting to mention additional dependencies that have to be installed and additional config files that need to be tweaked in order for the steps to work.

BiteCode_dev 2y ago

Lot of good advice. I'll nitpick a bit. You can't tell your user to "echo 'awesomecopter' | sudo tee /etc/hostname" if you may have windows users. And even for purely linux user, "Good: Give the reader a bash snippet that evaluates conditional logic for them" is quite a scary wall of code for a beginner that as no idea why copy/paste that. All in all, don't confuse "giving the shortest path to a working solution" and "teaching", which both can be in a tutorial, but they have different goals and you should choose accordingly. I think the "Teach one thing" is probably the best advice in the article, and too often ignored. I remember as a kid reading Swinnen's book to learn Python and having to understand OOP with his example using ions was a terrible experience. And if you think "well you should have known that, they teach it in school", you are missing the point. That being said, writing an excellent tutorial takes a lot of work. Way more than a good-enough one. Choose wisely.

runevault 2y ago
I really wish more tutorial makers would do the "teach one thing". Like I dabble in gamedev, and most people who create content for it generate 45 minute to many hour long tutorials that are end to end, instead of teaching "this is how you deal with navigation" "this is how you handle movement" etc. Means people who want to learn stuff are stuck interacting with a massive block of stuff which makes extricating out the part they need and planting it in their own project wildly harder.
- BiteCode_dev 2y ago
  Yes, and then link this things to pre-requisite, and show how several of those one-things come together in a separate piece. But again, it's a LOT of work to do that. E.G: To write "https://www.bitecode.dev/p/back-to-basics-with-pip-and-venv https://www.bitecode.dev/p/back-to-basics-with-pip-and-venv", I need to be able to rely on "https://www.bitecode.dev/p/installing-python-the-bare-minimum https://www.bitecode.dev/p/installing-python-the-bare-minimu..." which in turn needs to rely on "https://www.bitecode.dev/p/ultra-beginners-first-steps-for-the https://www.bitecode.dev/p/ultra-beginners-first-steps-for-t...". That's almost 9000 words, or 10% of the average novel size just to give beginners a good chance of success on one single topic. Between doc, tutorials, FOSS and forums, the entire software industry is just standing on a gigantic pile of billions of hours of free labor.

yoz 2y ago

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.

__mharrison__ 2y ago
I often use doctest to ensure my books "compile". Students hate it when your code doesn't work.
ChrisMarshallNY 2y ago
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. [0] https://github.com/LittleGreenViper/DemoCustomChartApp/tags https://github.com/LittleGreenViper/DemoCustomChartApp/tags [1] https://github.com/ChrisMarshallNY/ITCB-master https://github.com/ChrisMarshallNY/ITCB-master [2] https://littlegreenviper.com/miscellany/ https://littlegreenviper.com/miscellany/ (not every series is a tutorial).

jen20 2y ago

My pet peeve is code along the lines of: if err != nil { // handle errors } Or: try { // something that can fail } catch (Exception e) { // handle exceptions here } It's usually laziness from the author, but not stating _what types_ of error may occur and how should typically handle them is a plague on documentation and tutorials.

deleted 2y ago

[deleted]

lincpa 2y ago

[dead]

chocoboaus2 2y ago

This is REALLY good.

tolciho 2y ago

> Make code snippets copy/pasteable Naw, copying and pasting won't develop touch typing nor muscle memory skills. The prompt is sort of a context indicator for the command, as other comments indicate. Also if you're using one of those horrid browsers with CSS support who knows if there are characters that do not display but are included in what is copied. Security risk? Well, you started a chonky browser with a bad security record, so uh additional security risk. Also they probably should be able to type out the commands by hand at the speed of thought, or the commands should be put into a Makefile or script or done via configuration management. Making it easy to copy and paste? Well, if you want to train people to mindlessly copy-n-paste who knows what to who knows where, I guess. Doesn't sound like that would train people to engage deeply with the material. If there's a bigger code example I just put a "=> foo.lisp" link '(this is for Gemini (no, not the Google whatever nonesense (McCarthy invented AI to get money)), the modern web being too much yuck these days) so they can download the whole file. > Use long versions of command-line flags What are these? I'm on OpenBSD. More seriously, long flags may or may not help±quick! what does --fake-super for rsync(1) do?—and taking a peek into the manual (another reason I'm on OpenBSD) is sort of a spaced repetition to refresh you on what the flag does, and maybe to scan the list of options to see if anything new jumps out at you (or, at a certain age, what you've forgotten). Close engagement with the material (howeversomuch the learner hates this, as such brain exercise uses up precious energy) is probably a good thing. (Yes, I know that OpenBSD supports but generally does not document various wacky --from-backside-of-gnu flags.) > Teach one thing I am too fond of puns (and have ulterior motives, given the excess of car sitting in America, and the consequent loss of blood to the brain) to apply this in any meaningful way.

Fr3dd1 2y ago

For that topic some nice additional stuff: https://diataxis.fr/ https://diataxis.fr/

remoquete 2y ago
Diataxis gets often linked around here. It's simple, but by no means the solution to great docs. For more info, see https://idratherbewriting.com/blog/what-is-diataxis-documentation-framework https://idratherbewriting.com/blog/what-is-diataxis-document...

mongol 2y ago

What do you think about writing a tutorial without explaining terminology, but then ask an LLM to generate some kind of terminology index that shows at hover over the terms? If I am writing a tutorial it will take me much longer to explain terminology that I assume is known before. I can see the author's points, but all things considered if I am writing "for free" I don't want to spend unneccessary time. Letting the tutorial be my words, and the terminology index be that of an LLM may be a good balance?

supriyo-biswas 2y ago
This is similar to Msty's[1] "Delvify" feature that generates links for keywords in a given text, with the ability to "delve" into each highlighted topic. While I'm unfamiliar with how it's implemented there, I can certainly see this working with multiple rounds of prompting, and possibly some external data sources and human curation to ensure that the terminology index is actually useful to readers. [1] https://msty.app/ https://msty.app/

cloogshicer 2y ago

Fantastic article.

ChrisMarshallNY 2y ago

Thanks for posting this. It’s an excellent example of clear, useful writing, about a topic that could use all the help it can get.

laurentlb 2y ago

A good tutorial should be reviewed and tested by a second person.

bandrami 2y ago

Let me add: Specify up front date and software version. I can't stress this enough. As the CADT release cycle becomes ubiquitous we're approaching a situation where many tutorials are outdated by the time you finish them.

tommica 2y ago
What is CADT? Computer-Aided Design and Testing?
- bandrami 2y ago
  Sorry, I didn't realize that abbreviation had lost currency. Cascade of Attention Deficit Teenagers https://www.jwz.org/doc/cadt.html https://www.jwz.org/doc/cadt.html
  - cookie_monsta 2y ago
    Maybe because it never had currency?
    - bandrami 2y ago
      It absolutely did. It was even part of the Init Wars (prayers, sorrows)

nemetroid 2y ago

I think many of these rules are good, but that there's a too strong focus on ensuring that shell snippets are copy-pasteable without inspection. This comes at the detriment of other considerations, and I think some of the advice goes too far. Especially so when it comes to the different package names on different Debian versions: what originally was a oneliner is now fifteen lines long with six different branches. What should the reader do if the copy-pasted code fails? How do they know which part failed? What is an "/etc/os-release"? Yes, the happy path becomes simpler, but the reader will struggle to recover from any errors.

taeric 2y ago

If you haven't, I highly recommend taking a look at Knuth's manuals. Even if you are completely uninterested in METAFONT or TeX, they are a delight to read and I would hold both up as a very good aspirational target for software manuals.

wiradikusuma 2y ago

For those who can't find other people as your guinea pig, this is the trick I use: After finishing your tutorial, just wait for a few days, and try following it yourself, in a fresh env. I'm cursed (blessed?) with fish memory so after a few days I forgot everything I wrote.

javier_e06 2y ago

I thought that using Makefile targets was the shortest friendliest to show what a project can do. Turns out make and Makefiles can be mysterious when they fail. Tutorials are "best-effort" and often don't dwell on the rabbit-holes they create when a poor soul runs astray of the sunny path. Example of a good tutorial: Python's powerline shell: https://github.com/b-ryan/powerline-shell https://github.com/b-ryan/powerline-shell The README is succinct. Well put together.

ozim 2y ago

A developer who’s new to the React web framework won’t understand terms like “JSX transpilation” or “reconciliation engine.” They probably also won’t understand “SPA,” “soft reload,” or “virtual DOM” unless they’ve worked with other JavaScript frameworks. Unfortunately if you don’t use that, your beginners will have hard time to believe you are “guru” that they seek. Like if they find other guys tutorial with fancy words they will flock there - looking for some magic trick or some revelation that will hopefully come down on them while reading bunch of hard words without understanding. Most tutorials are like that for this reason. If you want to teach people author is right - if you are cynical and just want to earn money on a tutorial that’s a different thing. One upside - people quitting “hard” course most likely will be embarrassed to ask for return of money as they would feel it is their fault they did not learn as topic is hard. If they feel topic was easy and they did not learn, that’s probably guy making tutorial not knowing enough. My cynical take :)

egberts1 2y ago

Look at all the US Army training movies from the 1950s. Those are near perfect.l tutorial.

uvtc 2y ago

A rule I try to follow: don't waste your reader's time.

lsofzz 2y ago

Thank you.

tdehnke 2y ago

Love it - I'd add to ensure you clearly specify what version numbers you are writing for, and include a date of your writing. Things change a lot between Version 3 and 6 of something, and something written 5 years ago may no longer apply or be valid today.