News for hackers. Stuff that matters.
Re:WTFM - Write The Freaking Manual by dredmorbius on Friday September 28, 2012 @03:22PM (#4587310)
I fully endorse this. Coming from a sysadmins / devopps perspective, documentation is key to providing a reliable, dependable, available, scalable service. And dramatically improving the quality of my life.

How that documentation is written also matters. A lot.

Much proprietary documentation is also crap, for numerous reasons. Marketing having too much say is key (every reference to a Trademarked(r) Name(tm) Phrase(c) is both fully expanded and badged. Might keep the marketers and lawyers happy, but it's hell to read. Descriptions are vacuous to the point of idiocy ("More magic: select this option to enable more magic") -- tells me absolutely nothing not inherent in the control, and in particular, fails to tell me what the effect of enabling "more magic" is (feature name changed, but this construct is all too common in docs).

Usage notes and examples are mandatory.

As much as Free Software docs are pilloried, I still find that they tend to compare favorably with non-free docs.

Noted here: https://plus.google.com/104092656004159577193/posts/bLaDaXNe...

Re:WTFM - Write The Freaking Manual by incision on Friday September 28, 2012 @05:41PM (#4587935)
Coming from the same perspective, I agree completely.

Software pushers all seem to give the same puzzled look when I ask to see their full docs before evaluating their product.

It's exactly as you describe, if the documentation isn't sufficient for me to learn everything I could possibly need and likely want to know about how things work - I can't confidently design, build, scale or support it.

Documentation in the "Enterprise" world seems almost intentionally bad, as if to force customers into professional services and support contracts for products which lack the proper design to be sold as full on SaaS.