Honestly, as a newbie to Linux I think the ratio of well documented processes vs. “draw the rest of the fucking owl” is too damn high.
The rule seems to be that CLI familiarity is treated as though its self-evident. The exception is a ground-up documented process with no assumptions of end user knowledge.
If that could be resolved I think it would make the Linux desktop much more appealing to wider demographics.
That said, I’m proud to say that I’ve migrated my entire home studio over to linux and have not nuked my system yet. Yet… Fortunately I have backups set up.
ExcessShiv@lemmy.dbzer0.com 1 month ago
Yeah the documentation (if it even exists) is usually clearly written by people intimately familiar with the project and then never reviewed to make sure it makes sense for people unfamiliar with it.
SexualPolytope@lemmy.sdf.org 1 month ago
Relevant xkcd
wick@lemm.ee 1 month ago
Bold of you to assume I know how to read!
teft@lemmy.world 1 month ago
This is why Technical Writer is a full time job.
Semi_Hemi_Demigod@lemmy.world 1 month ago
It’s also why the humanities are important. Stemlords who brag about not doing literature classes write terrible documentation.
AlexWIWA@lemmy.ml 1 month ago
“set all environment variables”
mesamunefire@lemmy.world 1 month ago
More recently its go to discord for the env…no joke.
AstralPath@lemmy.ca 1 month ago
The mistake is the assumption of a certain level of end user knowledge.
Semi_Hemi_Demigod@lemmy.world 1 month ago
You have to assume some level of end user knowledge, otherwise every piece of documentation would start with “What a computer does” and “How to turn your computer on.”
I’ve found the best practice is to list your assumptions at the top of the article with links to more detailed instructions.
GBU_28@lemm.ee 1 month ago
Why’s that a mistake? Not everything is built for a novice
bl_r@lemmy.dbzer0.com 1 month ago
This is why I did a “walkthrough test” when I had to write documentation on this sort of thing. I’m a terrible technical writer, so this shit is necessary for me.
I grabbed my friend who knows enough about computers to attempt this, but not enough about infrastructure to automatically know what I meant when I was too vague.
Took two revisions, but the final document was way easier to follow at the end
sugar_in_your_tea@sh.itjust.works 1 month ago
That’s why blog posts rock. Most popular projects will have a dozen blog posts for different configurations. For example, when looking to set up NextCloud, I found docs for almost all combinations of the following:
It does take some knowledge of each of the above if you need one of the few configs that’s not available on a blog post, and some of the posts are outdated, but with a bit of searching almost everything is documented by someone on the internet.
This shouldn’t be necessary (official docs should be more comprehensive), but at least it’s available.
cron@feddit.org 1 month ago
I’d rather have a great documentation than five different blog posts, where some of them might be outdated, wrong or insecure (and you only find out later).
But yes, they are helpful and easily available for popular software.
harsh3466@lemmy.ml 1 month ago
Okay, please point me to the blog posts that helped you with collabora/onlyoffice. Thanks have NEVER been able to get that to work with my nextcloud (currently using the Docker AIO).
JackbyDev@programming.dev 1 month ago
Reminds me of the time I asked a question about a Magic: The Gathering card tomy local game store’s Facebook page. The card was Sublime Archangel. I asked what happened if it gave a creature Exalted that already had one. Someone sarcastically replied that it already says it on the card. I was a new player, how was I supposed to parse the phrase “If a creature has multiple instances of exalted, each triggers separately”? For all I knew that could mean that they didn’t stack because they would need to trigger together. I didn’t have the vocabulary to understand those things.
I try to remember this when explaining what I might believe are simple concepts to people because that person really upset me.
hperrin@lemmy.world 1 month ago
I don’t think it’s (just) that. It’s also a different skill set to write documentation that it is to write code, and generally in these kind of open source projects, the people who write the code end up writing the documentation. Even in some commercial projects, the engineers end up writing the docs, because the higher ups don’t see that they’re different skill sets.
marcos@lemmy.world 1 month ago
That’s just sloppiness.
The information that familiarity gives you is “WTF does this field means”, and it’s the only thing that’s actually there. How you get a value and how a value is formatted are things no amount of expertise will save you from having to tell the computer, and thus you can’t just forget about.
(And let me guess, the software recommended install is a docker image?)