Ceki Gülcü wrote:
> At 12:31 10.01.2002 -0800, you wrote:
> >Ceki,
> >
> >I basicly agree with Jon on this one. Documentation, like the current manual, I
>prefer to see as part of the project. However, a book on log4j -- how it works, how
>to modify it, etc with more extensive code examples as such -- would certainly be
>something appropriate to do for-profit outside of apache. Take a look at the
>O'Reilly books and you'll see many examples of that sort of thing. If you
> >do decide to go down the book writting path, I can get you in touch with O'Reilly
>through one of their current writers.
>
> I guess I don't understand the difference between good manual and a book. What is
>the difference?
>
> The current short manual is about 15 pages long. The current long manual is 50 pages
>long. A book would be around 200-300 pages long. Is it length that differentiates
>documentation from book?
> Or is it paper versus digital? Can it be that the difference is artificial? It's an
>honest question!
>
in short -- yes, yes, and (somewhat) yes.
(I was going to go back and compare the short vs. long manual but I can't seem to find
the long manual on the site at the moment so this won't be too detailed).
In my opinion, idealy the project manual would be somewhere between the short and long
manual in length. The user list often contains some very basic questions so the short
manual is not sufficient. However the long manual has more than needed to use log4j
and do basic extensions.
A book would go beyond both. A book would describe how to configure log4j for a great
variety of situations. It would describe and explain -all- the appenders (possibly
including various contributions), how they work, when to use them, the pros and cons,
etc. A book should talk in detail about sub-classing things like Logger, Appender,
etc including a full example of how to do that. The book could
include the reasoning behind various choices, a comparison with other logging
frameworks, wrappers to use the JSR47 API with log4j, and maybe even the history of
log4j.
The manual should be enough for a developer to use log4j and some pointers on
extensions. A long manual would describe some of the guts of log4j. A book would
cover all that, plus reasons for choices, details on everything, how to expand on
log4j, and maybe even where log4j is headed in the future.
>
> The long version of the manual still requires a lot of work. Imagine if the long
>manual were inserted back to the distribution, who would continue enhancing it? It
>couldn't be me could it? I mean how could I maintain the manual and at the same time
>write a book?
>
While you could certainly do both since the long manual should have a different goal
than a book, I imagine you'd be too busy with the book to want to do both. Log4j
needs the short manual updated more than it needs a long manual.
>
> Assuming I started to write a book based on the long manual, wouldn't this create
>friction between me (the book author) and the author of the manual?
>
I wouldn't think so. A 200 page book is a lot more work than maintaining a 15-40 page
manual.
>
> If the manual were both complete and polished, who would buy the book?
>
Ever seen how many books on the Java API there are? Javasoft maintains the javadoc,
tutorials, there are a ton of online java resources, etc... but people still buy the
books. Perl is the same way. People like hard-copies of reference material. I
suggest you develop an outline, send it to publishers and let them worry about the
sales process.
>
> Anyway, I have not yet made up my mind on this. I need to think it over. Your input
>is much appreciated. In the mean time, the long manual will not go into CVS because
>the foundation strongly opposes content which it does not hold copyright to. I do not
>intend to break this rule again and create further trouble.
>
> >As for maintaining log4j I'm interested. You've covered the list so well I figured
>you had everything under control. Tell me more about what is involved and what you
>spend time working on for log4j and we can find a way to share the maintainence or
>shift it to me.
>
> Maintaining log4j basically means listening to users and implementing features that
>are most wanted. You must also innovate to keep running in front of the competition.
>Do I need to mention fixing bugs? testing? and testing? and testing?
>
> Are you sure you want this job? :-) Regards, Ceki
>
Yes.
What do you see as the current status of things? What needs work now, and what is in
the pipeline? What does 1.2 need to go beta and then as a stable release?
Regards,
Kevin
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
