[slf4j-dev] svn commit: r1331 - slf4j/trunk/slf4j-site/src/site/pages

[Thorbjoern Ravn Andersen]

Ceki Gulcu skrev:
>
>>> - partially reverted 1329
>>>   Note on log levels needlessly clutters the text
>>>   
>> Have you considered *discussing* this before just deleting it?
>>
>> There is a VERY good reason for me writing this text.
>
> I am sorry for not discussing this particular item. Would you please 
> explain the reasons for writing the text in question?
The title of the web page is "SLF4J User Manual".  I understand this to 
mean that that document is a self contained unit describing the various 
facilities in slf4j.

You may notice on re-reading it, that it isn't.  The intended audience 
is people who happen to know about logging frameworks ALREADY, and the 
document tries to convince the audience that slf4j is great.  This has 
previously been much worse and appears to me to originally have been a 
"JCL bad, slf4j good" document which has slowly migrated to be a general 
powerpoint-like presentation.  (The FAQ shows this too).

For this document to be true to the title, I believe that at LEAST the 
following needs to be defined for an *uninitiated* audience:

* what IS a logging framework?

* what situations would it be reasonable to do logging?

* the concept of log levels and the historic background.

* the way stacktraces may be attached to a log event

* proper explanation of {} placeholders and how to use them in pre-Java5 
and after Java 5 (varargs)

* examples of using MDC (which I wholeheartedly feel should have a more 
telling name).


I invite you to consider whether you agree with this :)


-- 
  Thorbjørn Ravn Andersen  "...plus... Tubular Bells!"