Re: Documentation Standards was Re: [ox-en] UserLinux
- From: "Niall Douglas" <s_fsfeurope2 nedprod.com>
- Date: Fri, 05 Dec 2003 22:03:21 -0000
On 5 Dec 2003 at 13:31, helvetius ntlworld.com wrote:
I'm interested in the (implied? or am I reading that into your post?)
idea of documentation standards being an essential part of what makes
Free Software Free (or "Common" in the best sense). Especially given
that the generally appalling standards of documentation seem to be one
of the biggest current obstacles to promoting Free Software (BTW if
anybody knows where I can find some decent documentation for MinGW,
I'd be very interested...)Can you pass on any links where the Debian
FS guidelines explicitly cover documentation? Any other related
sources would also be of great interest.
Some programmers, who regrettably appear to be concentrated within
certain parts of the free software movement, take the view that
computer programming should be returned to a medieval tradecraft
whereby the tradesperson holds all of their skill in memory and
experience and form guilds to maintain it not becoming public
knowledge. Needless to say, anything approaching reasonable
documentation is a distinct no-no.
It is however easy to read conspiracy into programmers skipping good
documentation. To be fair, it's far more likely that many programmers
are slightly autistic and thus writing English is much harder than
writing code. Nevertheless, I can see some being motivated by a
desire to return computing back to the "golden age" when it was
"pure" though of course, they'd never ever admit that.
When it comes down to it IMHO, the code can be as technically
outstanding as it likes but it's still shoddy software if it doesn't
come with good documentation. And I do use "come with" here as in
meaning that the documentation should be as easy or easier to get
than the software itself (how many people evaluate a library via
looking purely at its source? Sure, you do that to evaluate code
quality, but not (ideally) to evaluate its API).
Cheers,
Niall
_______________________
http://www.oekonux.org/