Follow

If you write a tutorial, don't cover up all the mistakes you made along the way. Include them in detail!

Reading a success story is nice, but as so often in life, you'll learn so much more from all the mistakes you make, and all the issues you run into... and so will your audience.

@fribbledom
The thing is, some people read a tutorial when they need the thing done NOW and they only skim through it instead of reading it like a book. They want the minimum information necessary to achieve the task. And a description of failures, and wrong commands, would only confuse them.

Hm... maybe sth like a section at the bottom explaining "known mistakes" would be better?

@Wolf480pl

I guess you could also split it into paragraphs and annotate them accordingly.

From another point of view though: unless you're doing really groundbreaking work, chances are the most basic tutorials with all the compressed information already exist. Adding your personal experience to the mix still adds a lot of value then!

@fribbledom Not necessarily groundbreaking, but niche work.
There's a lot of stuff that's undocumented.

@fribbledom when i replaced my battery for my psp(by modifying a retail hobby battery instead of using those awful chinese ones) the guide author covered all his mistakes and it was shocking how informative leaving those in was

@fribbledom Not to mention that if people are searching for error codes &c they will find your writeup more easily

@fribbledom Exactly!
This is the major mistake profs make in lecture too.
They do exactly the same perfect thing every time semester after semester instead of varying.
It's what I loved about the early vids on Kahn Academy - he recorded his mistakes and efforts to get to the solution.
Filling up a board and then slamming it over out of the way (or erasing it!) and saying that it's "trivial to derive yourself later" is bullshit arrogance.

@fribbledom I think you only learn from mistakes...

If something goes right you don't know if it was because of what you did or just chance...

But if it goes wrong, you certainly know what *not* to do!

@fribbledom I could see this in a howto, but not in a tutorial. For a tutorial user, the project is likely to be dropped at the first stumbling point, and a deeper understanding is not the point of a tutorial.

@fribbledom yup, can confirm. 👍

On one blog post I explained how I discovered Linux was a bad choice for an old iBook G4, then covered the limitations of the PPC build of OpenBSD that did actually work. The latter led to package fixes!

In my most recent post building a retrogaming PC, I mentioned initially bought the wrong sound card. I was thanked by somebody on birdsite (before I left) for saving them from the same mistake.

@bobstechsite @fribbledom Older mac's are hit or miss with Linux. The Intel models were easier but still not easy.

Sign in to participate in the conversation
Mastodon

Server run by the main developers of the project 🐘 It is not focused on any particular niche interest - everyone is welcome as long as you follow our code of conduct!