On Fri, 2002-03-22 at 17:47, Philipp K. Janert wrote: > > 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.) >
Agreed, except I don't think your subjective comments are necessarily appropriate for a top level page. Its unlikely that in "several days" you have been able to objectively judge the status of all the projects. Such information is the responsibility of those project committers. > - 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. > Agreed. I think the "marketing" came out of someone else's comments as the discussion went on. > - 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. > In general, Jakarta committers vastly underestimate the importance of a wide audience. I like what Eric Raymond has to say on the subject in the Cathedral and the bazzar. Your users are your testers. Producing quality software requires a massive real world validation. (At least for something like POI, I could never hope to amass the data that users have provided). And as you mention are your pool of new recruits. For all of the time they swear they don't want users...if you watch you'll see them constantly campaign people USE their pet projects. So this is IMHO a paper-tiger party line. > - "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. > I totally agree. I have a downer on Javadocs. Javadocs are the bare minimum that should be provided. They are NOT documentation they are published comments. API docs are less then sufficient, they are the pungent glue that real documentation should be pasted upon. Any project that says the Javadoc is its documentation, I consider "not ready for prime-time". That being said, I take an action approach to this. As I have time I contribute documentation to projects that I see that don't meet my documentation requirements for use. > - 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. > Well thats the kicker. If you don't maintain it, it goes away :-). > - 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". > I think maintaining project news on an overview is not realistic. I know I don't want to update it everytime something happens on POI. The front page news is sufficient (I never notices the news section). We have a page that captures the latest release, thats a bit more detail than I'd want to keep updating on an overview. > 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? I think you've done that already. > - leave it as is? > - drop it altogether? > - replace it with something altogether different? > > Keep patching.. Don't give up. Any contribution that requires comment on the general @ jakarta list is subject to this "trial by fire" for some reason. The good news is once you pass over the hot coals it doesn't hurt as much. I'd like to invite you to come take a closer look at the POI project. I'm constantly asking for people to flame us on the documentation and I rarely get any takers (or at least any takers who have ACTUALLY READ the documentation). We'd really like your help. We don't have as many requirements or interested parties at that level and I'm sure I speak for all of us when I say your efforts would be most appreciated. Critique, contributions and any other assistance you can provide in the documentation arena. -Andy > 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]> > -- http://www.superlinksoftware.com http://jakarta.apache.org/poi - port of Excel/Word/OLE 2 Compound Document format to java http://developer.java.sun.com/developer/bugParade/bugs/4487555.html - fix java generics! The avalanche has already started. It is too late for the pebbles to vote. -Ambassador Kosh -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
