On Wednesday 26 December 2007 08:52:08 am Robert P. J. Day wrote: > On Thu, 27 Dec 2007, Ed Greshko wrote: > > Robert P. J. Day wrote: > > > by the way, the above is still not annoyance-free: > > > > OK.... > > > > So, I gather from all of this that the existing documentation, > > links, and whatever doesn't measure up to what you need or expect. > > Would that be a fair summary? > > > > Is the question then, how can documentation be improved for the > > average user? > > all i'm suggesting is that it took an inordinately long time to figure > out what should have been a two-minute exercise. i'm guessing that, > in most cases, readers aren't interested in a long-winded overview of > things -- they just want to know what commands to run to get > something done, which is all i wanted in the first place. > > in short, what people might want is a fedora "cookbook" with tight, > concise recipes that just plain work, out of the box. if they choose > to read up later on the underlying operations, then that's their > choice.net > > rday I am quite sympathetic to your issue, Robert, but have only limited optimism that the matter will get satisfactorily resolved. Fedora is by design a fast moving distro, and documentation, even with good resources, is always behind any given software. The lifetime of correct simple documentation is, it seems to me, limited and unknown. Given that clear simple technical writing is hard, what are the odds that capable optimists will emerge in sufficient numbers? And where is their effort best directed? to parts of Fedora that change only slowly? I often wish for better docs for even simple utilities (the man pages are routinely useless as tutorials) but don't see a reasonable framework into which I could contribute my pickiness about spelling and clarity. I once worked on a project hosted in France, editing English docs written by a native French speaker. I rewrote for idiom and spelling. Handy that I had a background as a programmer, since the docs were internal and for a library that end-users would basically never see directly. Then the project went bust for lack of available energy on the part of the lead. Well, it was instructive if only of limited effect. But it rather damped my willingness to do it all over again. Dave > -- > ======================================================================== > Robert P. J. Day > Linux Consulting, Training and Annoying Kernel Pedantry > Waterloo, Ontario, CANADA > > http://crashcourse.ca > ======================================================================== -- There is no single government agency that views sustainability through a broad lens, taking into account the values of the people affected by government decisions. Any model of sustainability that is driven solely by an economic engine is deficient if it is incapable of taking into account social values. Mr. Justice David Vickers, BC Supreme Court in Tsilhqot'in Nation v. British Columbia,2007
