I'd like to reply to comments made by several posters:
First of all, non-funded open-source projects (which is what this is)
are usually done because someone needs a tool *themselves*. That person
clearly does *not* need documentation.
The truth is, *every* project, your own private projects, or someone
else's *needs* documentation. Its just fine if you don't do it on your
private projects, because you aren't affecting anyone else. But as soon
as you bring up a community around it, ask for contributors, etc., it
becomes a shared, formal project. As soon as that project is shared, the
knowledge of its usage needs to be shared. Documentation is non-negotiable.
If *you* need documentation,
that's not the problem of the person writing the software.
It absolutely is. They have the knowledge. They know how it works --
moreover, they know how it is *supposed* to work. Another party cannot
account for that.
In practice
developers do write some documentation themselves; in some cases the
documentation is very good. However it's not something that a user
community can *demand* of the unpaid creators of a tool. And neither can
we users demand that the developers delay releasing functionality they
want because they haven't documented it enough for us to use.
First off -- this isn't about economics, its about the pursuit of
excellence in development, and doing a project right. If someone wants
to share a project, and invite my cooperation, feedback, and submitting
of code, which I have already in my first month of using it, then I see
no problem whatsoever in requesting that the project provide
documentation commensurate with the level of feature.
Secondly, this is open source. If you really want to know how a
particular piece works, read the code. It's the final and official
documentation. Nothing is being hidden from any user of the software.
This statement right here summarizes everything that's wrong with the
attitude surrounding open source. The point of open source is not to
trade the time you would have developed something on your own with time
instead going on an easter egg hunt trying to figure out how something
works. You turn everyone into a developer that way, and you burn
everyone's time that they either could have been writing their own
custom solution which would meet all their own needs, or time they could
have been contributing to the project and making it better. Having to
tinker, dig, and read source code just to figure out how to use
something is just trading development time for Google time -- and you
end up paying big money either way.
There is one reason and one reason only for no or poor documentation on
any product, commercial or not: laziness. Neglect, that's it.
Thirdly, documentation is *never* complete. There's always someone who
Not a reason not to document, and anyway, it isn't true. Documentation
can be as complete as the code. There's no magic to that.
And fourthly, the developers are often *not* the best people to write
the documentation. For someone who knows all the details of an
implementation it's quite hard to step back and write good introductory
tutorials.
Absolutely they are. Especially in open source, they are the ones who
know how something works, and is supposed to work. You cannot have
someone who doesn't understand the product document it. What you are
referring to is the inability of many developers to communicate concepts
effectively, which is an entirely different issue. If a developer can't
communicate their thoughts, well then, that's something they need to
work on. But it doesn't mean you lower the bar on your project.
Just about every successful commercial product ever released has had
books about it published *months to years* after the product was
released. MS-Office tutoruals, RedHat administration guides, Hibernate
"developers notebooks". Continuing the documentation process after the
product is released is *normal*.
Not analog. Because other projects were bad, doesn't mean you should
aspire to the lowest common denominiator. Because there's a bum drinking
a 40 oz of Colt 45 out of a paper bag down the street doesn't mean
that's a good reason for all of us to do it.
The most important piece is the first, though. As users we shouldn't
demand but instead contribute. Updating the main site directly isn't
possible, but improving documentation via a wiki is.
I'll reiterate: you cannot document accurately and completely if you
don't know the full scope of feature, which is clearly locked inside the
heads of a few developers. The web site doesn't even come close to
describing things to the point where someone could follow up with
documentation. If I could document maven without having to spend months
upon months trying to elicit answers to questions and Googling the great
unknown for Maven 101 information, I probably would. As it is, I'm about
a gnat's eyebrow away from writing my own custom alternative to maven.
It doesn't compute -- for the great product maven is, the lack of
documentation has turned the experience into a huge time pit. Every
problem is a new plugin and a new configuration option or file and a new
frontier of undocumented stuff, and a whole new cycle of trial and error.
Please understand that my comments are not directed at any person, they
are directed at an attitude I have seen perpetuated throughout my
career, which is negative. Let's call it what it is -- the lack of
documentation is just cutting corners. Its trading away completeness,
and excellence in a project for what is fun, and/or what we aren't
willing to wait for. The idea that because something is free, or
open-source, that it suddenly becomes this new entity that no one needs
an instruction manual for is just ridiculous. Its all just a piece of
software. And as a comment on a completely different issue, if
developers are going to discard the responsibiility to communicate their
thoughts, ideas, and designs well, you can say goodbye to your jobs,
because you've just severely commoditized whatever you have to offer as
a developer by eliminating the primary reason not to send your job
overseas (effective communication).
Whatever is worth doing, is worth doing well.
Brad
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
