I kind of agree with this. I think a wiki is fine for collaborative documentation but now that everything is in final release, it's probably time for a new form of docs. An example of how poor the docs are on the wiki: there are 2 or 3 separate links for the tag references and only one of them points to the references that are actually valuable. The others point to what looks like placeholders.
I'm happy to discuss possibilities and give my opinion on the docs but unfortunately my time is rather limited. So I guess my opinion needs to be taken with a grain of salt. If there was a gameplan for a doc revision, though, I could probably sign on to handle isolated parts. As it is, it appears that the doc roadmap is along the lines of "if someone wants to write docs, have at it". That could keep the docs in a scattered state, as they are now, for a long time. -----Original Message----- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Charlie Morss Sent: Friday, February 27, 2004 7:41 PM To: [EMAIL PROTECTED] Subject: Re: [OS-webwork] docs are important Just to put my 2 cents in here. I'm a huge fan of WebWork and XWork and I recently started a new project (not my first WW project, just getting things setup at a new clients site). I just wanted to download WebWork2 and XWork (the prebuilt binaries and the src). It took me forever to find any distribution for this, let alone the documentation. And yes, I need to say that the docs are not what they could be. I think that WebWork and XWork are just great tools, however, if I had not purchased the the "Open Source Java Programming" book and had peers that were wrestling with the problems as myself I would have thrown in the towel a long time ago. We need to have WW and XWork meet the 5 minute rule: a developer should be able to go to a single source, find all the docs nicely laid out (see Hibernate's doc index), and have easy access to all the files - all releases including source for current and past, and easy access to any forums/mailing list archives. In 5 minutes or less they should be able to make a simple determination as to whether tool will work for them or not. The decision needs to be based on the technical merits of the tool, not on their ability to find information in 20 different locations. Basically a wiki is not the tool for this. For the future of these most excellent tools I ask that everyone involved please reconsider the use of the wiki as the information repository. It just doesn't do the job. Thanks for listening to my rants, Charlie On Feb 24, 2004, at 4:56 AM, Lars Fischer wrote: >> So what is so wrong with the WW2 docs? > > They're outdated and incomplete, a useful example is missing. > The example war doesn't work with WebLogic. Navigation sucks with this > WIKI thing. > > Look at Hibernate or Spring where an excellent reference manual is > provided. > > For the XWork/WebWork part I can recommend the book "Java Open Source > Programming" (though it's full of errors and extremely expensive). > > Regards, > Lars > > I was able to build the Wafer >> Weblog with it. While I was actively working on the Expresso >> framework we got hammered by user for the same reason, they said our >> documentation sucked. Problem was just throwing more "documentation" >> at the website wasn't the solution because then you ended up with all >> of these poor flowing documents. It is very hard to write good >> documentation!! >> After >> having worked with many frameworks myself I feel that the best thing >> that could be done to help out newbies is one, have good javadoc. >> That >> is the easiest because the issue of "flowing" is not an issue. The >> second would be to have a good example. When I was working with the >> Maverick framework I used their friendbook example as about as much >> as their API's. So the webwork team could go off and create an >> example >> (great!) or you could steal one that already exist from someone else >> (hint Wafer). >> >> Kris Thompson >> >> -----Original Message----- >> From: [EMAIL PROTECTED] >> [mailto:[EMAIL PROTECTED] On Behalf >> Of Bill Lynch >> Sent: Friday, February 20, 2004 12:34 AM >> To: [EMAIL PROTECTED] >> Subject: [OS-webwork] docs are important >> >> All, >> >> Ouch: >> http://www.depeupleur.com/blog/TT_blog/archives/000019.html >> >> We got zinged there -- Jason, thanks for the good followup. Let's use >> this as impetus to improve the docs! >> >> I recently started working on the WW2 docs and I'd be happy to help >> out with XWork if someone could give me cvs commit & Jira access to >> that proj. >> >> Anyone interested in taking this over? >> http://jira.opensymphony.com/secure/ViewIssue.jspa?key=WW-477 >> >> Cheers, >> --Bill >> >> >> >> ------------------------------------------------------- >> SF.Net is sponsored by: Speed Start Your Linux Apps Now. >> Build and deploy apps & Web services for Linux with a free DVD >> software kit from IBM. Click Now! >> http://ads.osdn.com/?ad_id=1356&alloc_id=3438&op=click >> _______________________________________________ >> Opensymphony-webwork mailing list >> [EMAIL PROTECTED] >> https://lists.sourceforge.net/lists/listinfo/opensymphony-webwork >> >> >> ------------------------------------------------------- >> SF.Net is sponsored by: Speed Start Your Linux Apps Now. >> Build and deploy apps & Web services for Linux with a free DVD >> software kit from IBM. Click Now! >> _______________________________________________ >> Opensymphony-webwork mailing list >> [EMAIL PROTECTED] >> https://lists.sourceforge.net/lists/listinfo/opensymphony-webwork >> > > > > ------------------------------------------------------- > SF.Net is sponsored by: Speed Start Your Linux Apps Now. > Build and deploy apps & Web services for Linux with a free DVD > software kit from IBM. Click Now! > http://ads.osdn.com/?ad_id=1356&alloc_id=3438&op=click > _______________________________________________ > Opensymphony-webwork mailing list > [EMAIL PROTECTED] > https://lists.sourceforge.net/lists/listinfo/opensymphony-webwork > ------------------------------------------------------- SF.Net is sponsored by: Speed Start Your Linux Apps Now. Build and deploy apps & Web services for Linux with a free DVD software kit from IBM. Click Now! http://ads.osdn.com/?ad_id=1356&alloc_id=3438&op=click _______________________________________________ Opensymphony-webwork mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/opensymphony-webwork
