honestly, I couldn't agree more with everything you have here, except
I wish we had Confluence as a wiki (yes, this opens up spirited debate).
Paul
On 25/07/2008, at 8:00 AM, Matthew Vernon wrote:
The entire Logging Services Project has a bit of a problem with
documentation.
Much of this is difficulty of finding information, but the project
could use
more documentation in general. A particular problem is the use of auto
documentation that mixes user and developer information. As a user,
I had a
difficult time sorting through class documentation that mostly dealt
with
internals that I never needed to use.
A partial solution might be to use a wiki to document user
information. Links
to the various API docs would allow people to dig deeper. One of the
major
benefits of this approach is that one site could cover all of the
log4 series
and common information (like configure files) would not have to be
duplicated.
It would also be convenient to have some function call documentation
show the
calls for different programming languages side by side.
Now as a long term MediaWiki user, MoinMoin sure seems primitive to
me. Maybe
it
just a little work to make everything look nice. A key factor to
consider is
whether wiki.apache.org is the right place for this as far as implied
endorsement. Also important is what license the content is under. I
am a fan of
making documentation public domain (like the MediaWiki help pages),
but I don't
know if that is a problem for ASF. I do know that a wiki full of
Apache 2
license statements would be a pain in the arse.
--Matthew Vernon
[EMAIL PROTECTED]
Paul Smith
Core Engineering Manager
Aconex
The easy way to save time and money on your project
696 Bourke Street, Melbourne,
VIC 3000, Australia
Tel: +61 3 9240 0200 Fax: +61 3 9240 0299
Email: [EMAIL PROTECTED] www.aconex.com
This email and any attachments are intended solely for the addressee.
The contents may be privileged, confidential and/or subject to
copyright or other applicable law. No confidentiality or privilege is
lost by an erroneous transmission. If you have received this e-mail in
error, please let us know by reply e-mail and delete or destroy this
mail and all copies. If you are not the intended recipient of this
message you must not disseminate, copy or take any action in reliance
on it. The sender takes no responsibility for the effect of this
message upon the recipient's computer system.
