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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
