Re: Documentation and Usability
On Sat, Jan 17, 2004 at 12:10:38PM -0600 or thereabouts, Mac McCaskie wrote:
> Colin and Stephen
>
> Let me understand you correctly. You admit the documentation needs
> improvement and might be slightly un-helpful to noobies. So your
> solutions are (1) to tell (not ask) the noobie to do fix it (the same
> one that doesn't know enough about how to use the system) and (2) blame
> the stupid noobie for is ignorance by not working hard enough.
>
> Solution one will perpetuate the inadequate documentation problem.
> Solution two will enforce the "Brotherhood of Linux Clubhouse Rules"
> and perpetuate the frustration of future noobies.
>
> In my two months of seriously "getting down" with debian I have run into
> the following:
> -A major installation package was broken in the stable release, and
> discovered via this list and other sources that the problem was known
> with no intention to fix it.
> -Found packages with no available documentation
> -Found man pages that did not match executable supplied help.
> -Found man pages with circular "help" i.e. "foo is foo-like because it
> is derived from foo's parent"
> -Discovered the "best support organization" is impatient with frustrated
> noobies.
>
> Mac <your turn> McCaskie
Rather than debating Mr. McCaskie, why don't you get to work, ask a
maintainer how you can help with writing some better documentation? I
assume you have faith in your abilities to write technical documentation.
You seem to be able to critique well enough. Proof is in the puddin,
there fella. Another thing you might consider, is that the world of
Linux is not necessarily English centric. Many of the developers speak
English as a /second/ language. So, I'm sure a potential offer of
assistance, would be genuinely welcome, by such developers/maintainers.
Not every day that a competent native English speaker offers to help.
Go for it, stop wasting valuable energy debating, action there big fella.
--
Stephen
---------------------------------------------------------------------------
"You know the world is going crazy when the best rapper is a white guy, the
best golfer is a black guy, the tallest guy in the NBA is Chinese, the Swiss
hold the Americas Cup, France is accusing the US of arrogance, Germany
doesn't want to go to war, and the three most powerful men in America are
named 'Bush', 'Dick', and 'Colon'"
--unknown
Reply to: