Ceki Gülcü wrote: > >Hi All, > >I am pondering whether it is possible to earn revenue by offering >log4j documentation online, a bit like what JBoss is trying to >do. Needless to say, the log4j API (the software) will always be >licensed under the Apache Software license and would include some >basic documentation. However, writing good documentation is very time >consuming and I'd like to see if I can get paid to do it. > >This documentation will be based on the long log4j manual which was >until recently part of log4j 1.2 alpha3, alpha4 and alpha5. However, >the latest alpha6 does not include it. This document carried a clearly >visible copyright notice. It was always copyrighted by me and not the >ASF. > >Do you think this is an honorable approach? Your comments on the >subject are welcome. Thank you. > 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.
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 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. 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. R.Parr Temporal Arts -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
