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.
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.
SwordInStone@lemmy.world
on 05 Jan 12:25
nextcollapse
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. 🫠
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.
copygirl@lemmy.blahaj.zone
on 05 Jan 12:14
nextcollapse
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…
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.
SwordInStone@lemmy.world
on 05 Jan 12:27
nextcollapse
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…”
copygirl@lemmy.blahaj.zone
on 05 Jan 14:53
collapse
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 two: they work only on Ubuntu, they will break your Debian or Debian derivative.
dajoho@sh.itjust.works
on 05 Jan 12:42
nextcollapse
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?
SwordInStone@lemmy.world
on 05 Jan 13:41
nextcollapse
not my title, but it is kinda in your face.
I agree “recommendations” or “pointers” would not come across as so selfğrighteous
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.
BaldManGoomba@lemmy.world
on 05 Jan 21:28
nextcollapse
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.
Boomkop3@reddthat.com
on 05 Jan 23:41
nextcollapse
Why not just:
you’re gonna learn this this and that
…
now you should know what this this and that is
FizzyOrange@programming.dev
on 06 Jan 09:02
collapse
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
Randelung@lemmy.world
on 06 Jan 01:34
nextcollapse
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.
threaded - newest
This is beautiful. If only all tutorials were actually written well.
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.
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
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
I don't quite agree that for a beginer being presented with
is better than
All 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.
.
It’s not the same, though. One will stop if a previous command fails, the other will continue.
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.
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…
…is instead turned into this single command with even more confusing syntax for beginners:
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), whatsudois 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.
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?
not my title, but it is kinda in your face.
I agree “recommendations” or “pointers” would not come across as so selfğrighteous
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.
Because rules are meant to be broken :3
I just wanted to read that cartoon, here it is:
<img alt="" src="https://infosec.pub/pictrs/image/4360d7a7-30c1-4d97-9944-f791b49fdc48.png">
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 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.
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
“Pointers” twitch
:*
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.
.