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