Config docs or a User's Guide (Was: Help on property file settings for Appenders and Layouts)

[Mark Masterson <ma...@compuserve.com>]

Hi,

Listen, I'm hardly a Log4J guru, but this topic is discussing something that
I think that many of us have encountered, as users.  Likewise, I've given
some thought to taking a whack at a users' guide, as many other people
probably also have.  In fact, here at my company, for our people internally,
I already have a working version of one, although it would need a lot of
work to make it "generic" enough to be an all purpose guide - it's currently
very specific for our projects.  Having said that, and having already
admitted my lack of guru-dom, I'm a pretty good tech writer, and I don't see
any reason why a real "User's Guide" would not be possible.  The assumption
here is that folks like Ceki, Anders, Paul, Jim and so on would be available
to me to play the guru role and help me fill in the blanks.  Assuming I can
count on that, I'd be willing to try producing a real "User's Guide for
Log4J" (which would then subsume the proposed config doc), and more
importantly, maintain it.

Reaction?
--Mark


---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-user-unsubscribe@jakarta.apache.org
For additional commands, e-mail: log4j-user-help@jakarta.apache.org

Re: Config docs or a User's Guide (Was: Help on property file settings for Appenders and Layouts)

[Paul Glezen <pg...@atdial.net>]

Mark Masterson wrote:
> 
> Hi,
> 
> Listen, I'm hardly a Log4J guru, but ...

That makes you the perfect person to start writing one.

> The assumption here is that folks like Ceki, Anders, Paul, Jim 
> and so on would be available to me to play the guru role and 
> help me fill in the blanks.

A good assumption.  Writing documentation for a product/concept is the
best way to learn about something.  When I wrote the DeepExtensions
document, I included a "Look Under the Hood" section.  I wasn't sure
about everything.  But that's ok.  I just stated things as I saw them,
even if I wasn't completely sure.  The reviews were able to catch any
problem.

Ceki wrote a kind of user's guide only six months ago.  But it seems
that log4j has expanded quite a bit since then.  I even wonder if there
is a place for an educational road map.  In some cases, this is simply
the table of contents for the user's guide.

My guess is we would want to take this opportunity to unify some of our
current documentation.  I think of two principal conflicting goals with
documentation: completeness and getting people started quickly.  For
this reason, many products have a "User's Guide" and a "Reference
Guide".  Mark could write a new "User's Guide".  His experiences in
writing this could produce a viable table of contents for the reference
guide (based on things both included and left out for sake of space). 
We could all then take ownership of various chapters of the reference
guide and produce them individually (according to some agreed upon
template).

Many people judge the maturity of a product by how well organized and
thorough the documentation is.

- Paul
-- 
Beware of bugs in the above code.  I have
only proved it correct, not tried it.
-Don Knuth

---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-user-unsubscribe@jakarta.apache.org
For additional commands, e-mail: log4j-user-help@jakarta.apache.org