Dear Friends!
First off, many thanks to Ted for posting my Draft Jakarta
Overview, thus allowing everyone to review it, and many thanks
to all who provided feedback on it, for or against.
I would like to comment on some of the issues raised.
- Purpose and Redundancy:
To clarify the intended purpose of the document, it may help
to explain how it came about: When I started to hang around
the Jakarta website, my first desire was to get a good, high-level
overview, so that I would then know where to dig deeper into those
projects which are relevant to me. I followed every link on
the main page to each individual project's homepage, and then on
to the sub-projects where appropriate, compiling exactly the
information in the submitted document. Took me several days.
Assuming that others will have the same experience (and Chris'
and Endre's emails seem to indicate they do), I decided to make it
available.Just having all the information in one place can help a
lot! (The overview on the Jakarta homepage, although great, does
not contain either subprojects, or status information.)
- Audience and "Marketing":
The document is directed towards people who may not be familiar
with all the projects that exist under the Jakarta umbrella.
Specifically, it is directed towards users, who hope to find
something useful for their own projects. (Those users may turn
into contributors over time!)
I cannot understand why Leo and Ceki refer to the document (and,
by implication, others like it) as "Marketing" - a term which
carries in this context clearly condescending connotations.
I don't think documentation is marketing - and what I tried to
provide is simply documentation, not different in principle
than Javadoc, only at a higher level.
It is also simply not true, as Ceki believes, that "everybody
knows Jakarta": from the inside it may be hard to conceive how
large and confusing the entire Jakarta project can appear to
the outsider.
- Users vs Developers
I sense a certain ambivalence towards making Jakarta projects
easier to use - Ted, for instance, points out that more users lead
to more support questions (and mailing list discussions, such as
this one). But isn't this stance slightly contradictory?
If you don't want users, why publish your products? (By the way,
I, as a user, am grateful that you do make them public - and that's
why I am trying to support this project where I believe it needs
it!) Just for balance, Endre puts usability first - I guess, it's
a balancing act.
- "Hello, World" and Javadoc:
Danny suspects that I "have a downer on Javadocs". That is not
quite correct. I think Javadocs are great - as a reference. I
think they are terrible for just finding out what a project is
all about. Overview, Tutorial, Reference: three very different
things!
I would like to repeat my conviction that for first-time users
(and all of us are at that stage at some point in our lives!)
worked examples would be immensely helpful in understanding the
scope and purpose of each project. It would be great if this could
come either out of the projects themselves, or from the larger
user community. It is great to see Andrew encourage contribution
of documentation to individual projects.
- Personal Assessment and Maintenance:
Several people pointed out that the document contains subjective
assessments. This may be true, and may have been unfortunate.
I think a much better approach would be if the status ratings,
for instance, came out of the projects themselves, along the
lines of: 'alpha', 'beta', 'stable', or somesuch (and I would
like to thank Andrew for suggesting that anybody unhappy
patches it - and which is already happening!).
In terms of maintenance: Once everything is set up, this should
not take too much effort (just updates of revision numbers and
release dates, really). I think I also hinted (cough) that I
might be willing to help with that (to the degree that I have
available resources, of course) provided that maintaining such
an overview document at all is solidly supported by the community.
- Commons Components:
I am sorry, I have overlooked the Commons Components page, which
provides the equivalent of what I tried to do (for the Commons
project) - my mistake. I apologize. And thanks to Rodney for pointing
it out.
Now what?
=========
It seems to me that overall a high-level Jakarta overview is
being considered useful, or at least "mostly harmless" by most.
The main contentious issues seems to be the perceived subjective
assessments, which are already being patched out: by people
closer to the projects and therefore more knowledgeable than me.
That's great! The "News" section has also disappeared - I consider
that a bit sad: I think some measure for the activity of the
project would be helpful, but there may be better ways to determine
it. I would have thought that the date of the most recent release
would not be considered a "subjective judgement".
The question is: Now what?
Should we:
- collect suggestions to improve the initial draft so that the
majority here considers it a good thing to have and develop it
further along those line?
- leave it as is?
- drop it altogether?
- replace it with something altogether different?
Best regards,
Ph.
-----------------------------------------------------------------
Philipp K. Janert, Ph.D. [EMAIL PROTECTED]
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
