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).


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
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

Paul Smith
Core Engineering Manager

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: psmith@aconex.com  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.