I don’t quite agree that for a beginer being presented with
sudo apt update && \ sudo apt install --yes software-properties-common && \ sudo add-apt-repository --yes ppa:deadsnakes/ppa && \ sudo apt install --yes python3.9is better than
sudo apt update sudo apt install software-properties-common sudo add-apt-repository ppa:deadsnakes/ppa sudo apt install python3.9All those symbols and “–yes” used to feel quite cryptic to me.
yeah, I’d give it as 4 separate copy-pastable commands and then write “or as one command…”
If it’s a beginner trying to learn those commands, definitely the latter.
If it’s a beginner trying to set up their environment for the actual thing they’re trying to learn, then a fire and forget single command is more user-friendly.
The argument is that a beginner might not notice a command falls. The && prevents further execution.
Personally I’ve seen that happen several times myself. Beginners are just not used to reading the cmd outputs and I can’t blame them. There are many CLI tools with awful error reporting out there.
That’s why showing the expected outcome is also very important. It can feel very verbose, but the number of times I’ve been unclear as to if something worked because the documentation goes on immediately to the next step without demonstrating the success/failure states is extremely frustrating.
It’s not the same, though. One will stop if a previous command fails, the other will continue.
deleted by creator
I just wanted to read that cartoon, here it is:
all of these tips are moot because of SEO. If you want anyone to actually read your article you still have to write for both the reader and the search engine unfortunately.
So, tips like the “Write clear headings” are often hard to actually implement as search engines prioritize keywords in headings and you’d be outranked by a dude who doesn’t do that 99% of the time.
deleted by creator
“Pointers” twitch
:*
This is beautiful. If only all tutorials were actually written well.
Am I the only one who finds the title abrasive? Why “rules”? Who are you and why should I listen to you? Will you send the tutorial police around if I ignore you? Maybe “recommendations” would be a better choice?
Unless it’s filled with specific uses of MUST, SHALL, and MAY, it’s just opinion. This is the internet, so the IMO SHALL be assumed.
not my title, but it is kinda in your face.
I agree “recommendations” or “pointers” would not come across as so selfğrighteous
Because rules are meant to be broken :3
I stopped reading after the first example. One of them is described as “good” and the other as “bad”. The bad one though does not actually fix the errors in the good one, but just leaves them out. The good one seems to be only an introduction. The bad one seems to be trying to convey content. Surely not very well, but comparing an introduction with content is like comparing apples with pears.
The two examples at the beginning are completely separate examples, not rewrites of each other. The comparison is in the readability for beginners, not the content.
sorry for your disappointment
The first two or three examples are really bad but the rest are quite good.
If only this stuff wouldn’t eat so much time. I’ve been writing a library and it often feels like I’ll spend 1 hour documenting for maybe 5 hours of implementing a feature. And I’m not even terribly happy with the documentation yet. 🫠
That’s still not a terrible ratio
Think about the wording of the headings so that they communicate as much as possible without sacrificing brevity.
Which of these tutorials would you rather read?
- Go
- Installation
- Hello, world!
- Deployment
Or this?
- Why Choose Go?
- Install Go 1.23
- Create a Basic “Hello, World” Go App
- Deploy Your App to the Web
honestly, neither of those? I get the general point, the first one looks careless and vague, but the second one looks AI generated and needlessly long, hard to skim for what I’m looking for. Why do the headers say Go 3 times when I already know I am in a Go article? Why is the specific version in that one header (even if you will be pointing them to a specific one in the content)?
Why not just:
- you’re gonna learn this this and that
…
- now you should know what this this and that is
That’s the “say what you’re going to say, say it, then say what you said” advice from school. It’s ok if you don’t know any better, or maybe for particularly boring work presentations, but it isn’t a golden rule that most people blindly repeating it think it is.
Think about the best presentations you’ve seen. They never do that. They’re engaging enough that you don’t need repeat things three times.
I didn’t get that in school, perhaps we’re in a different country or something. It’s not about being engaging or following a guideline. It’s about setting goals and checking if you achieved them.
Every audience is different, every student learns at their own way and pace. A one size fits all solution doesn’t exist. Some presentations may be awesome, but that takes more than just a good script and slideshow
Why not both? People are motivated or get things in different ways sometimes I just need the command other times I need to understand why. As for titles of sections the funny or longer chapter lines I might remember better than the simple one.
