2 ms·
> Nobody takes any time to read the documentation That assumes many things: First: there is documentation available (many MANY stuff doesn't have docs, especi
by 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)