Re: Maven documentation (was Re: how to include all dependencies in your jar)

["Calen Martin D. Legaspi" <ca...@orangeandbronze.com>]

+1

I think we've been spoiled by the open-source projects that are funded by
big companies, that may have paid technical writers.  In my use of a lot of
other open-source software, such as linux utilities, I've relied on mailing
list archives, forums and unofficial How-Tos on blogs of people not
connected to the development team.

I believe the crux of open-source is contribution, and so if one wants good
documentation, one should think about wrting it himself.  This doesn't have
to be such a big effort.  Replying to mailing list questions or recording
your discoveries in a blog are incremental ways to contribute.

--
Calen Martin D. Legaspi
Sun Certified Enterprise Architect
Software Engineering Director, Orange & Bronze Consulting, Inc.
President, PinoyJUG - "Developers building community." -
http://groups.yahoo.com/group/pinoyjug
The Third World Developer Blog: http://calenlegaspi.blogspot.com

On 3/7/06, Simon Kitching <sk...@apache.org> wrote:
>
>
> 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. If *you* need documentation,
> that's not the problem of the person writing the software. 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.
>
> 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.
>
> Thirdly, documentation is *never* complete. There's always someone who
> doesn't understand a topic, or who wants to do something out of the
> ordinary. I'd consider your request to package dependencies of a module
> inside the jarfile as an example of that. It would be frustrating to see
> new functionality kept unreleased because *some* of the potential users
> are not able to understand it or want to use it in unexpected ways.
>
> 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.
>
> 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*.
>
> 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.
>
> Regards,
>
> Simon
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> For additional commands, e-mail: users-help@maven.apache.org
>
>