Welcome to the main community in programming.dev! Feel free to post anything relating to programming here!
Cross posting is strongly encouraged in the instance. If you feel your post or another person's post makes sense in another community cross post into it.
Hope you enjoy the instance!
Rules
Follow the wormhole through a path of communities !webdev@programming.dev
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.
"Pointers" twitch
:*
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.9
is better than
sudo apt update
sudo apt install software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt install python3.9
All those symbols and "--yes" used to feel quite cryptic to me.
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.
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.
Is providing a number of commands to use that require user input really that bad? When people start tinkering with the command line, first of all they shouldn't trust just anything on the website blindly, which at the very least requires a basic understanding of how to enter commands, and respond to the terminal asking for input. The following "bad" example..
sudo apt update
sudo apt install software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt install python3.9
..is instead turned into this single command with even more confusing syntax for beginners:
sudo apt update && \
sudo apt install --yes software-properties-common && \
sudo add-apt-repository --yes ppa:deadsnakes/ppa && \
sudo apt install --yes python3.9
Sure, it's convenient, but if you just throw blocks of code at people to run, are they really learning anything?
A better approach would be to have a quick tutorial on how to use the terminal and what the $ and # symbols mean (though they could be CSS decorators that can't be copied), what sudo is and warning people about running untrusted commands on their system. Then you just link to that at the top saying something along the lines of "if you're unfamiliar with running commands, and the following seems confusing, check this quick summary", behind a question mark icon connected to each block of commands, or similar.
I absolutely abhor it when the command includes $ that copies with it. It means nothing to the beginner's and the pros know it is a command.
I wrote under other comment:
yeah, I'd give it as 4 separate copy-pastable commands and then write "or as one command..."
Yeah, it should not be part of the text just like line numbers shouldn't be part of the code on a code hosting site, yet it can be visible, no? Later it does recommend using $ to distinguish command and output. Is it now okay for a beginner to be confused about what it means?
Rule number one: be wary of ppa.
Rule number two: they work only on Ubuntu, they will break your Debian or Debian derivative.
I just wanted to read that cartoon, here it is:
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
This is beautiful. If only all tutorials were actually written well.
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)?
I got the same sort of impression in the "Write for beginners" section. The "good" example is like 3x as long but contains less actual information. The reader is already looking up a tutorial, you don't need to sell them on what they're about to do with marketing speak. I've really come to value conciseness in recent years.
Why not just:
...
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
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 first two or three examples are really bad but the rest are quite good.
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.
I prefer my tutorials without reading someone's life story at the beginning. The intro contains so little info compared to the number of words being used. This reminds me of looking up a recipe and having to scroll past an essay on the history of someone's grandmother. I like it when documentation is as dense as possible, and ideally formatted in a logical way so it's easy to skim. Big paragraphs of English do not achieve this.
sorry for your disappointment
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
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.