At 09:15 11.01.2002 -0600, Randall J. Parr wrote: >I know of many, many good projects (both open source and commercial) that have >withered and died because there was not sufficient documentation on how to actually >use it. The successful ones seem to provide considerable documentation and/or >community support above and beyond basic API (ie Javadoc) documentation. How >successful would the Apache web server or Samba be if all that was available was API >docs and minimal documentation? How much progress could it make if the groups were >constantly inundated with the "but how do I ...." questions easily covered by decent >"how-to, why-to, ..." documentation.
Randall, Thank you for your frank comments. Log4j will continue to ship with documentation which will also continue to improve. Please see my previous mails for the distinction between the short manual and long manual. >I believe it is very important that any project hoping for wide-spread and/or long >term support provide documentation of the quality that HAD been part of log4j. This >availability of this documenation (and the fact the project *seemed* to feel this >documentation was needed) is part of the reason I chose to use and follow log4j over >other available packages. I totally agree. >I do not believe providing good documentation precludes books. (As someone pointed >out) Look at all the Perl, Java, Apache, Samba, ... books that have been written; >Many be the same folks that also wrote and donated the original extensive project >documentation. > >I understand and agree that writing a book is a lot of work. 1/3 of the work of >writing such a book is figuring out (or remembering) how the stuff works and >including in the book the documentation that *should* be there in the first place. >Another 1/3 is creating and explaning lots of examples of to use, extend, apply, ... >the software. The final 1/3 is organizing and making all this a pretty, formatted >package and providing it printed form. > >People seem willing to pay for this last third even when the first 2/3 are available >free as part of the project. >For example, people seem to buy the Eckel "Thinking in Java" books and the Java >Tutorial books even though the entire book is available free in HTML and PDF format. > >Having said all this, IMHO, pulling documentation that has been included as part of >the project leaves a very bad taste. It leaves me very concerned about using the >package going forward. I also feel this may well prevent more wide-spread adoption of >the package. I, for one, would love to see log4j used in LOTS of products. This is a common misunderstanding. The documentation that existed in log4j 1.1.3 remains in the log4j 1.2-alpha6 distribution. In fact, the javadocs and the short manual have been improved in the various log4j 1.2 alphas compared to 1.1.3. >I would stongly suggest the project needs to define the level of documentation >required for the project to be used successfully and gain audience while not placing >undo burden on the groups. I think that level is all the API / configuration >documentation, a getting started, and at least a handful of "real-world" examples. >Javadocs and "look at the source" just are not sufficient. I agree. -- Ceki Gülcü - http://qos.ch -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
