Billie Walsh said the following on 11/19/2012 11:19 AM:
The issue with the {expletive deleted} manuals is that for a non-technical, ignorant, noob they are not written well. Most are written by the person that does the programming [ or at least that is my impression ]. The person my be the most fantastic, super, programmer in the world but they can't write manuals that non-technical, ignorant, noobs can understand.
Once again I say that you have confused purpose. The manuals are a technical reference and are meant to be a minimalist though sometimes of necessity there is a lot to document) one in a very prosaic and fixed format. They are not meant to be how-to guides. Since you are complaining that they are dry, technical and not in literate English, then they meet their design constraints and I feel that is good. The problem is that you are expecting MAN pages to be something they are not, and that his 'how-to' guides, ones that lead you though "Frequent Used Examples". See http://en.wikipedia.org/wiki/Manual_page#Layout for an example of the template/headings. There are plenty of how-to guides out there, and they are not so formally structured. They might also miss out on some aspects of the technical capabilities that are mentioned in the MAN pages. Please do not confuse a technical reference (think of it as a blueprint with the dimensions and parts list) with the operating guide. If we were talking an automobile or aircraft "kit" and you made the complaint that the blueprint was overly technical, not well written for a noob and done by the designer, then how justified would you feel? Not least of all when there is an operating manual as well?
I can do a man [ whatever ] and spend hours trying to decipher what is presented.
So can the more experienced of us as well. That's not the point. The more experienced of us know that the manual is a technical reference and not a operating manual and will look elsewhere. And, as I say, "Context is Everything". Some pages, such as http://linux.die.net/man/3/template, presuppose that you know Perl. If you don't, then of course the documentation is gibberish. You have to take the time to learn what it is about. mc /usr/share/doc firefox https://www.google.ca/search?q=linux+docs+howto rpmshare doc zypper search doc
Might as well be written in Martian.
Try reading some papers on political economics if you want to see examples of pure gibberish. Especially ones dating from the last century. Claiming that anything and everything should be intelligible to 'boobs' without them putting in the effort to learn the context and culture and framework is ridiculous. -- “Anti-intellectualism has been a constant thread winding its way through our political and cultural life, nurtured by the false notion that democracy means that 'my ignorance is just as good as your knowledge.'” ― Isaac Asimov -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org