4 ms·

System administration isn't any different. I run into examples all the time. I see "documentation" that is a saved website from some "How to install X on Y" bl

System administration isn't any different. I run into examples all the time. I see "documentation" that is a saved website from some "How to install X on Y" blog entry. These blogs are so bad. If you google 'install x on ubuntu' you will get a bunch of hits on 'tech' blogs. Many of them just copy and paste from the same original source. Nothing gets explained, things are installed with terrible defaults, steps are performed that aren't necessary, and necessary steps are also performed! You'll see every bad habit in the book. StackOverflow is even worse. Well, ServerFault is where admin questions should be posted but they end up on SO. "I did xx and it if fixed it", usually xx has nothing to do with it or is something like 'chmod 777' Nobody takes any time to read the documentation, learn anything or even question, 'what does this actually do?'. It's sad.

battery_cowboy 7y ago
I've been writing an article like that, but I'm trying to go through every manual and ensure it's correct and current. You wouldn't believe the amount of work I'm putting into this, and for no reason but to practice writing or something,I don't even know anymore. I get why people write the shitty articles now, it's really hard to write a good article about a simple install. That's no excuse, they should just not be writing articles if they don't want to work, but I understand the reason behind the influx of crap.
mschuster91 7y ago
> Nobody takes any time to read the documentation That assumes many things: First: there is documentation available (many MANY stuff doesn't have docs, especially in the Javascript world, but it's become a "trend" in general software) Second: the docs are reasonably up to date (again, Javascript... webpack drove me nuts) and the software is backwards compatible so that docs/examples from the last version still work (again, webpack serves as a fine example) Third: the docs come with a reasonable amount of examples that cover common usage scenarios and edge cases that one may hit during implementation (Kubernetes on bare metal is just plain "fun") Fourth: the docs are legible and understandable without boatloads of domain knowledge and in coherent English (or if it's a regional thing, the locally dominant language)! When half the documentation suffers from typo errors, is badly formatted, or (common with offshored stuff) the reader needs more time to mentally translate the gibberish to "this is what the author could have meant", then a Google search is often enough the easier way. Understandability also includes organization: Unorganized wikis or "current version" scopes including stuff from years ago that clearly is outdated are a nightmare to use. Fifth (esp. applicable for new-ish GUI applications): documentation without illustration. No, your average user will not automatically associate your weird "flat design" button as "save". tl;dr: Docs aren't read 'cause they're unusable. Additionally, and this is another huge part: on Stackoverflow/Serverfault and many blogs there will be a comment section which I can glance over to see: is this answer correct/still applicable, what experiences did other people have, are there better alternatives... most docs don't have this proximity of documentation and feedback - except maybe PHP Core documentation, which on the other hand suffers from not being moderated (i.e. old/dangerous stuff isn't hidden)

battery_cowboy 7y ago

I've been writing an article like that, but I'm trying to go through every manual and ensure it's correct and current. You wouldn't believe the amount of work I'm putting into this, and for no reason but to practice writing or something,I don't even know anymore. I get why people write the shitty articles now, it's really hard to write a good article about a simple install. That's no excuse, they should just not be writing articles if they don't want to work, but I understand the reason behind the influx of crap.

mschuster91 7y ago

> Nobody takes any time to read the documentation That assumes many things: First: there is documentation available (many MANY stuff doesn't have docs, especially in the Javascript world, but it's become a "trend" in general software) Second: the docs are reasonably up to date (again, Javascript... webpack drove me nuts) and the software is backwards compatible so that docs/examples from the last version still work (again, webpack serves as a fine example) Third: the docs come with a reasonable amount of examples that cover common usage scenarios and edge cases that one may hit during implementation (Kubernetes on bare metal is just plain "fun") Fourth: the docs are legible and understandable without boatloads of domain knowledge and in coherent English (or if it's a regional thing, the locally dominant language)! When half the documentation suffers from typo errors, is badly formatted, or (common with offshored stuff) the reader needs more time to mentally translate the gibberish to "this is what the author could have meant", then a Google search is often enough the easier way. Understandability also includes organization: Unorganized wikis or "current version" scopes including stuff from years ago that clearly is outdated are a nightmare to use. Fifth (esp. applicable for new-ish GUI applications): documentation without illustration. No, your average user will not automatically associate your weird "flat design" button as "save". tl;dr: Docs aren't read 'cause they're unusable. Additionally, and this is another huge part: on Stackoverflow/Serverfault and many blogs there will be a comment section which I can glance over to see: is this answer correct/still applicable, what experiences did other people have, are there better alternatives... most docs don't have this proximity of documentation and feedback - except maybe PHP Core documentation, which on the other hand suffers from not being moderated (i.e. old/dangerous stuff isn't hidden)