Re: Documentation Standards was Re: [ox-en] UserLinux
- From: "Niall Douglas" <s_fsfeurope2 nedprod.com>
- Date: Sat, 06 Dec 2003 23:57:04 -0000
On 6 Dec 2003 at 10:20, Benni Baermann wrote:
Sorry, i dont get this. In my experience free software is the best
documented software available on this planet. Everytime i have to work
with proprietary software in the last 20 years it was very bad
documented. These days this is not very often necessary and i am glad
to work with better and better documentation. "Free software has no
documentation" was one of the oldest bias about it. (Ok, one exeption:
Gnome tends to mimic Windows that much, that it trys to have the same
stupid documentation. They have both very helpless helpfiles, which
explaines nothing but the obvious.)
You have more experience with free software than I, but I find myself
wondering "what planet is he on?". Maybe your definition of well
documented software is vastly below my own. The solution is for you
to point me towards what you think is a typical example of well
documented free software.
I'll start first: the best documented free software I've used so far
is the OpenSSL library - but I would still call it "okay"
documentation as it ain't great. Qt is not bad, but the library
misbehaves in ways the documentation should mention whereas OpenSSL
is better at this. Compared against MSVC's MSDN collection (which is
a great resource on the idiosyncracies of Windows), all these look
positively poor - to give them credit, Microsoft do document their
software even if it's often inconsistent and hard to find and the in
depth articles are something you must buy (expensive) books for with
Linux - Microsoft gives you this for free.
What kind of benchmark do I hold all software against? Probably the
Programmer's Reference Manuals for Acorn RISC-OS v2 - beautifully
bound books, plenty of space to add your own notes, lay open on your
lap very handily and apart from a few areas had a wealth of
information yet were concise. Of course, they fitted in well with the
whole ethos of that system.
By the way: the original thread focuses on _licenses_ for
documentation and not about the quality of it. But maybe i got it
completely wrong, my english is not the best.
You were right - my point was that the choice of license reflects the
motivation of the people writing the software. Some library writers
deliberately make the code obtuse with virtually no documentation so
they can call it free and market their book and consulting business
to unsuspecting punters who think "free" means free.
If you think I'm being paranoid, look at how many big free software
project programmers also have consulting divisions and write
programming books on their library. While many are honest, some are
just as exploitative as Microsoft, perhaps even worse as at least
with Microsoft you know what you're getting from the start.
Cheers,
Niall
_______________________
http://www.oekonux.org/