Re: Now what? (was: Jakarta Overview)
Philipp K. Janert [EMAIL PROTECTED] wrote on 23/03/2002 09:47:31 AM: [snip] 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. Except it also contained words such as immature, which border on the emotional. [snip] - Users vs Developers I sense a certain ambivalence towards making Jakarta projects easier to use - Ted, for instance, points out that more users lead I'll take personal exception to that comment. My first patches to a Jakarta project included documentation, and it's one of the main things I've done on Latka at this point. I think we'd all like the projects to be easier to use and understand, but I'll wager not everyone is comfortable that they can do it themselves. [snip] [snip] 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. 'News' as a measure of activity on a project is effectively useless. Commits/month would be a lot better. Given most jakarta projects have a nightly build, releases by themselves aren't as much of a milestone as people would think from the commercial point of view. Take Struts for example. I happily built production systems off pre-1.0 code for many months. There were no new betas, just updated nightly builds. The code was actively being developed, but why waste time on a release if there's no particular purpose? 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? Well, it's already being improved by being changed in CVS, and could easily be replaced with something altogether different over time. I'd much rather see the commons stuff removed and a pointer in place to the existing page, and some form of 'activity' in place of what was news. -- dIon Gillard, Multitask Consulting Work: http://www.multitask.com.au Developers: http://www.multitask.com.au/developers
RE: Now what? (was: Jakarta Overview)
- Audience and Marketing: Specifically, it is directed towards users, who hope to find something useful for their own projects. (Those users may turn into contributors over time!) It takes too much effort to support a user base for a project that changes rapidly (ie any 'alpha' status code). Hence these parts are not advertised very well. It should stay that way. 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. as dion said. When a project you are working on very hard for a long time is listed as immature or something like that, it is very hard to find the right wording for a response. - Users vs Developers again, I personally distinguish between alpha, beta and final releases. You only offer support (answers to mailing list questions) for released products. - Personal Assessment and Maintenance: 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. as we say: documentation is always welcome! Now what? = 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. it's simply not a good indicator. FA, almost nothing happens over at Avalon Framework, but it gets more releases than the way more busy other Avalon parts because it is, well, released. 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? it should, -- after consent by others here -- be merged with the current overview on the front page. That's imho, of course. greetz, - Leo Simons -- To unsubscribe, e-mail: mailto:[EMAIL PROTECTED] For additional commands, e-mail: mailto:[EMAIL PROTECTED]
Re: Now what? (was: Jakarta Overview)
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
Re: Now what? (was: Jakarta Overview)
On Sat, 2002-03-23 at 03:42, [EMAIL PROTECTED] wrote: Philipp K. Janert [EMAIL PROTECTED] wrote on 23/03/2002 09:47:31 AM: [snip] 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. Except it also contained words such as immature, which border on the emotional. I don't think he meant any harm. [snip] - Users vs Developers I sense a certain ambivalence towards making Jakarta projects easier to use - Ted, for instance, points out that more users lead I'll take personal exception to that comment. My first patches to a Jakarta project included documentation, and it's one of the main things I've done on Latka at this point. I think we'd all like the projects to be easier to use and understand, but I'll wager not everyone is comfortable that they can do it themselves. I get the same feeling often. Granted I think its probably part that most developers don't feel comfortable with their writing skills. [snip] [snip] 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. 'News' as a measure of activity on a project is effectively useless. Commits/month would be a lot better. Hummm...I'll put that comment in the pile of the most important activity in software development is programming pile of things I disagree with. Given most jakarta projects have a nightly build, releases by themselves aren't as much of a milestone as people would think from the commercial point of view. Take Struts for example. I happily built production systems off pre-1.0 code for many months. There were no new betas, just updated nightly builds. The code was actively being developed, but why waste time on a release if there's no particular purpose? Whoa...dude.. The release is the point when all the edges are smoothed and things are tied off. Release often. There is a difference between a build and a release. Its the point when an effort is made to make sure the documentation matches up and everything is *ready*. It a tracking point in the software lifecycle. If you never stop the bus then when can you paint it? 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? Well, it's already being improved by being changed in CVS, and could easily be replaced with something altogether different over time. I'd much rather see the commons stuff removed and a pointer in place to the existing page, and some form of 'activity' in place of what was news. -- dIon Gillard, Multitask Consulting Work: http://www.multitask.com.au Developers: http://www.multitask.com.au/developers -- 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]
Re: Now what? (was: Jakarta Overview)
At 14:47 22.03.2002 -0800, you wrote: - 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. I realize that you spent considerable amount of time editing the document. I appreciate the effort. I assure you that there is no condescension on my part, at least not intentional. The introduction in your email came through as here is the solution to all Jakarta's problems. I have a hard time accepting that as being the truth. 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. The Jakarta brand is very well known. What is less known are the individual Jakarta subprojects, in particular their relation with each other. I doubt the overview document will solve that conundrum. As I said in my previous comments, I do not have a problem with the contents of the document per se but the sprit in which it was presented. IMO, it would have been preferable to work with each individual subproject rather than start a new body of work but that was not my decision to make. Are you willing to continue maintaining it? Make sure that it is comprehensive, consistent and up to date? What will happen when you grow tired of it? Nothing is preventing you from continuing to work on the overview. If you persist, my -1 will be withdrawn or overridden. What is certain is that the overview is yet another brick on of the edifice of Jakarta. Philipp K. Janert, Ph.D. [EMAIL PROTECTED] -- Ceki My link of the month: http://java.sun.com/aboutJava/standardization/ -- To unsubscribe, e-mail: mailto:[EMAIL PROTECTED] For additional commands, e-mail: mailto:[EMAIL PROTECTED]
Re: Now what? (was: Jakarta Overview)
Andrew C. Oliver [EMAIL PROTECTED] wrote on 24/03/2002 12:39:09 AM: 'News' as a measure of activity on a project is effectively useless. Commits/month would be a lot better. Hummm...I'll put that comment in the pile of the most important activity in software development is programming pile of things I disagree with. Fine, but since commits aren't just programming, they're also docs, proposals etc, i feel it's a far more valid measure of activity than writing a news article. Given most jakarta projects have a nightly build, releases by themselves aren't as much of a milestone as people would think from the commercial point of view. Take Struts for example. I happily built production systems off pre-1.0 code for many months. There were no new betas, just updated nightly builds. The code was actively being developed, but why waste time on a release if there's no particular purpose? Whoa...dude.. The release is the point when all the edges are smoothed and things are tied off. Release often. There is a difference between a build and a release. Its the point when an effort is made to make sure the documentation matches up and everything is *ready*. It a tracking point in the software lifecycle. If you never stop the bus then when can you paint it? I agree, but you need a purpose for a release. Releasing just so it happens often is pointless. There should be a consistent amount of change/bug fixing/docs etc for a release to be made. -- dIon Gillard, Multitask Consulting Work: http://www.multitask.com.au Developers: http://www.multitask.com.au/developers
Re: Now what? (was: Jakarta Overview)
On Sat, 2002-03-23 at 17:38, [EMAIL PROTECTED] wrote: Andrew C. Oliver [EMAIL PROTECTED] wrote on 24/03/2002 12:39:09 AM: 'News' as a measure of activity on a project is effectively useless. Commits/month would be a lot better. Hummm...I'll put that comment in the pile of the most important activity in software development is programming pile of things I disagree with. Fine, but since commits aren't just programming, they're also docs, proposals etc, i feel it's a far more valid measure of activity than writing a news article. True. /snip I agree, but you need a purpose for a release. Releasing just so it happens often is pointless. There should be a consistent amount of change/bug fixing/docs etc for a release to be made. Agreed. But thats not a release. Thats called lying to yourself/others that you have a release when you really just have a build. -Andy -- dIon Gillard, Multitask Consulting Work: http://www.multitask.com.au Developers: http://www.multitask.com.au/developers -- 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]
Re: Now what? (was: Jakarta Overview)
Subject: Re: Now what? (was: Jakarta Overview) From: Jon Carnes [EMAIL PROTECTED] === Andrew C. Oliver wrote: 'News' as a measure of activity on a project is effectively useless. Commits/month would be a lot better. True. /snip I agree, but you need a purpose for a release. Releasing just so it happens often is pointless. There should be a consistent amount of change/bug fixing/docs etc for a release to be made. Agreed. But thats not a release. Thats called lying to yourself/others that you have a release when you really just have a build. -Andy I believe that you have to have a release periodically (even if the changes are not dramatic). These things are cyclical. If you want to keep the focus of your community, you have to generate releases. Agreed that they should not be pointless, but I can't imagine a truely pointless release. We always have *some* progress. -- To unsubscribe, e-mail: mailto:[EMAIL PROTECTED] For additional commands, e-mail: mailto:[EMAIL PROTECTED]
Re: Now what? (was: Jakarta Overview)
On Sat, 2002-03-23 at 21:25, Jakarta General Newsgroup wrote: Subject: Re: Now what? (was: Jakarta Overview) From: Jon Carnes [EMAIL PROTECTED] === Andrew C. Oliver wrote: 'News' as a measure of activity on a project is effectively useless. Commits/month would be a lot better. True. /snip I agree, but you need a purpose for a release. Releasing just so it happens often is pointless. There should be a consistent amount of change/bug fixing/docs etc for a release to be made. Agreed. But thats not a release. Thats called lying to yourself/others that you have a release when you really just have a build. -Andy I believe that you have to have a release periodically (even if the changes are not dramatic). These things are cyclical. If you want to keep the focus of your community, you have to generate releases. Agreed that they should not be pointless, but I can't imagine a truely pointless release. We always have *some* progress. I tend to differentiate between builds and releases -- 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]
Now what? (was: Jakarta Overview)
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: -
