Hi Jeff!
"Noll, Jeff HS" wrote:
> Not to get into a great big argument over OS version commercial
> products, but if OS projects expect to be taken with the same consideration
> as commercial they have to accept to be compared across the board. This
> includes documentation. You can't just pick and choose the battles you want
> to fight.
Yes you can (and should). Do you know why engineers are so bad writers
of user documentation? Because they are so embedded in the technical
point of view that it takes a big effort to revert to user mind. That's
why there are technical writers in the world.
Open Source is about scratching your itches (usually at what you do
best). I don't want lousy manuals written by overworked engineers --
that's worse than nothing. But some users have contributed excellent
guides, although they are not as handy as they should be.
That's the reason why it's so disgusting to hear folks complaining about
the docs. If you have an itch, you don't ask dad to scratch it any more
-- you know exactly the sore point. If you're willing to make the docs
better, I'm sure you'll get all the support you need.
> For the most part, the documentation in OS projects just plain
> sucks, if it even exists. Believe it or not this is one of the reasons OS is
> often frowned upon. Look at Microsoft, sure its close source, people may
> think it sucks, blah blah blah, but do you have idea how much information is
> on MSDN?
On MSDN you don't have access at the internal workings of software,
reasons behind design choices or bugs that have been corrected and are
recurrent. In the tomcat-dev archives you can find all of that and much
more.
On MSDN you cannot speak to the actual engineers that did the job and
drove the architecture forward. In the tomcat-dev list you can.
> The lack of documentation available goes against some very basic
> rules of Software Engineering. In the real world does this really matter? I
> dunno, but often times packaging and presentation, and a finished looka nd
> feel are the key to getting in the door and this is where most OS projects
> fail miserably.
Most open source projects fail in lack of commitment from the dev/user
community. Bad docs are just a consequence of poor user commitment (in
that field, in others like bug finding we excel).
> Because its free might be the reason the documentation sucks, it
> shouldn't be a justification. (not that i'm saying tomcat sucks, just
> argueing the point).
Un saludo,
Alex.
