Date: Tue, 13 Mar 2001 03:07:41 -0600 From: Mike Meyer <mwm@mired.org> To: "Doug Young" <dougy@bryden.apana.org.au> Cc: "Ted Mittelstaedt" <tedm@toybox.placo.com>, "Mike Meyer" <mwm@mired.org>, <questions@FreeBSD.ORG> Subject: Re: documentation issues generally Message-ID: <15021.58205.859557.268757@guru.mired.org> In-Reply-To: <02f601c0ab8a$adace680$0200a8c0@apana.org.au> References: <000601c0ab84$db0a6c20$1401a8c0@tedm.placo.com> <02f601c0ab8a$adace680$0200a8c0@apana.org.au>
next in thread | previous in thread | raw e-mail | index | archive | help
Doug Young <dougy@bryden.apana.org.au> types: > My point is that the "user-friendly" sites wouldn't be there at all if the > official documentation > fitted the needs of all users, rather than simply the experts. Would you please teach your mailer to wrap text properly, and not give us these sawtooth lines? While what you say is true, it's simply not possible to write text for all users. The man pages are arguably for experts. For the most part, they're meant to be references for people who already know the terminology and system, and know what command they want and are just double-checking the syntax or flags. The Handbook and FAQ are not at that level. It explains some - but not all - of the terminology. In spite of your contineued protestations that the official documentation doesn't have examples, the Handbook and FAQ *do* have examples. For instance, the majority of the entries in the sysadmin section of the FAQ seem to have explicit examples. Some of the others are explanations of the way things are, so examples aren't really relevant. All of them could be improved, but they aren't aimed at "experts". The sites you name - in my brief explorations of them - seem to be "I got it to work this way" type things. They don't seem to provide any more details than the FAQ or handbook entries, and often suffer from not having been checked by experts so that the quicker/better/more reliable methods that that show up in the FAQ and Handbook - with examples. > The same > situation applies largely > to "The FreeBSD Corporate Networker's Guide" & "The Complete FreeBSD" even > though > they appear to be targeted at least slightly higher up the experience scale. Slightly higher up the experience scale than you are, perhaps. But no matter how far down the experience scale you write, there'll always be someone below it. Write to your level, and then we'll have someone complaining that the official documentation doesn't explain how to use the coke holder. > Certainly newbies have a requirement for more explicit explanations. Windows demonstrates that that's patently false. Try finding *explanations* of things on Windows. Instead, you find click-n-pray type things. You can certainly make Unix work at that level - the commercial Linux distributions have been doing it for years. Of course, they are almost as unfriendly as Windows now, and I've deleted them all for one of the not quite so commercial ones. > Its obvious that most experts are against making man pages more of a > tutorial, so whats the solution ?? There's a good reason for not making the man pages into tutorials. I don't *want* to have to wade through parapraphs of explanation about what directories and files and symlinks and file systems are to find which flag reverses the sort order of a long directory listing. More importantly, I don't want to have to wade through the same paragraphs to check the options for ln, cat, mv, rm, and all the other commands that deal with files and directories. Of course, the solution is obvious - write the stuff you want. > The system > of merely telling newbies to RTFM just doesn't work unless the newbie can > comprehend some > of whatever manual. Seems to work quite nicely for mos of the things I answer on -questions. I've done as several experts have suggested at times & > spent $100 or so at a time on O'Reilly books (thats what they can cost in > OZ), 90% of which goes way over my head. I guess one can always read > whatever can be comprehended, try a few things, badger the list etc, but > thats frustrating for everyone. Sounds like you need to look for a lower level of book. I've heard good things about "Unix for people" but I am in no way qualified to recommend those books for you. > In many cases the explanation in the handbook could be improved dramatically > by the simple addition of a screenshot and/or example of usage ... in other > places adding an extra line or two would do the trick, however there appears > to be some sort of taboo against explicit docs. Well, if you believe they aren't explicit enough, quit wasting time complaining about it, and submit a PR with a couple of patches in it. Worst thing that could happen is they say know, in which case you're no worse off than you are now. More than likely, they'll accept it - in which case you've found a way to contribute something useful to the project. But I'm curiouas to what is insufficiently explicit about, say, 4.2.1, which gives you command examples showing how to find a port, find out more about the port, then make and install it. They even include the "cd" commands to needed to get to the right directory. > If as it appears to many of us the docs people guard their territory > jealously like priests / lawyers / medicos / etc, is there any reason why a > group of interested regulars couldn't create > a " Pedantic Supplement" or the like .... maybe just the standard handbook > with all the missing bits added (screenshots / step_by_step_explanations / > examples / etc) ??. The docs people are quite helpful and friendly to people who actually *write* things. They tend to ignore people who complain about the quality without doing anything, as they already have enough things to do. <mike -- Mike Meyer <mwm@mired.org> http://www.mired.org/home/mwm/ Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-questions" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?15021.58205.859557.268757>