logging-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Matthew Vernon <matt...@vernshome.net>
Subject Documentation
Date Thu, 24 Jul 2008 22:00:22 GMT

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

View raw message