Comments for https://refactoringenglish.com/chapters/rules-for-software-tutorials/
- MMatt
This is an awesome guide! I have to learn web technology from scratch for my job (I'm a Windows desktop app developer now). Going through bad tutorials have me fed up and want to give up. Every little thing I go to try requires a hundred other things that I don't have any knowledge of. The ultimate goal is to learn React and Docker on Linux, but as your examples show, they aren't the most user friendly. I wish all technical writers were as conscientious as you about their audience and what they are going through.
- KIn reply tosystem⬆:Magnus Lindberg @kajmagnus
Another idea: Q/A testing:
Find two technical, but not too technical, freelancers / coworkers, who want to work with you long term.
And when you're making a change to the tutorial, plus before you publish it the first time: Ask one of them to follow the whole tutorial from start again. (Two? If one is busy. And if the same person does it too often, they might accidentally start remembering things by heart, rather than reading?)
(Maybe you decided to not include this, for brevity. I mean, if one works in a bigger company, maybe it's pretty obvious to ask sbd to proofread & check if it works. At the same time, if one is alone? Then maybe nice to start thinking about this sooner, since might take a while to find someone?)
Such a nice tutorial about tutorials :– ) I'm going to re-read when it's time for me to publish a tutorial.
- MMichael Lynch @mtlynch
Thanks for reading, Magnus!
I think that's an excellent practice, but I left it out because it's not something I personally do. A few people have suggested this, but I'm not sure how they do this in practice.
Because you need to find someone who's:
- Is within the target audience for your tutorial
- Hasn't learned the information yet
- Wants to spend a couple of hours testing your tutorial and giving you feedback
As a solo dev, I'd find it hard to do this. Maybe solicit blog readers, but that's still a hard sell. But even when I worked at a company, I never experienced people testing tutorials on their co-workers in a formal way.
What's been your experience with finding testers?
The way I've come to do it is just publish my tutorials after testing them myself, but I make it easy to give me feedback (such as with TalkYard commenting support 😄) and revise based on actual readers reporting issues.
- KMagnus Lindberg @kajmagnus
What's been your experience with finding testers?
I tried some years ago with hiring freelancers via Upwork to try out the Getting Started instructions for Talkyard. (Not sure if that counts as a tutorial, but at least there's step-by-step instructions and code to copy-paste and run etc.)
I think it worked pretty well: Most people were technical enough to follow along & understand, while everything being new to them. — It was possible to, thanks to them, make the instructions less confusing, and fix some things that only worked on my laptop(s).
The annoying thing was actually the extra bookkeeping this meant O.o
(Hiring someone in a lower-cost-of-living place for a few hours is pretty affordable, and nice for them too :- ) I hope.)(But now the getting-started instructions have gone a bit out-of-date again, probably are in a bad shape.. Maybe time to do this soon again :- ))
But otherwise / most-of-the-time, I do like you: testing myself (only).
- MMichael Lynch @mtlynch
Oh, that's an interesting idea. That sounds much more practical than other suggestions I've heard. I might give that a shot.
- SIn reply tosystem⬆:Sebastian Aburto @saburto
Thanks for sharing this, I look forward to read the book!
- MIn reply tosystem⬆:Max Allan @maxa
Please add a bit about using the correct quotes in code snippets.
I often find people using "document" editors (like Word) to write their documents and anything in quotes ends up like “this” instead of like "this" (even in code because they just use "Font=Courier" for code instead of a proper code block).
Sometimes when you copy/paste the content into a terminal the "bad" quotes get replaced with special characters and it's obvious, sometimes they get quotes that look very much like straight quotes and it's a total nightmare to figure out where the problem comes from.“this” instead of "this" - M2In reply tosystem⬆:Me
Document all software version nunbers.
The number of times I've used a tutorial written on version X but with a newer version Y and had problems...- KMagnus Lindberg @kajmagnus
And Java imports! That's something I've found annoying with some StackOverflow answers: There's sample Java (or Scala) code, and they use different classes — but where do I find those classes?
Once I spent some time looking up the correct packages and
importstatements to add (so the answer became actually usable to me), and edited the StackOverflow answer so others wouldn't have to, too.Then he reverted my edits — removed the imports — because he liked it better that way, he said. A policy of his, sort of.
- TIn reply tosystem⬆:Tim
You think "Organizing Your Front-End Codebase in a Django Project" is more specific and less vague than "How to Combine Django with Front-End JavaScript"?
I have no idea what "organizing" might mean here. It sounds like it tells you what folder to put your CSS files in.
- MMichael Lynch @mtlynch
Thanks for reading!
You think "Organizing Your Front-End Codebase in a Django Project" is more specific and less vague than "How to Combine Django with Front-End JavaScript"?
I have no idea what "organizing" might mean here. It sounds like it tells you what folder to put your CSS files in.
Yeah, that's true. I was thinking that "organizing" does mean how to structure the project folders so that Django and a frontend framework play nice together, but I see that it's still pretty ambiguous.
I've replaced it with:
- Bad: How to Make a Compiler
- Good: How to Write a C Compiler in 500 Lines of Python
Does that feel clearer?