On Friday 30 April 2004 09:18 am, Ron Wheeler wrote: > Even "formal" documentation in open source projects is a bit iffy. > You can find some questionable information in Jakarta documentation > and some information where the author clearly did not have any idea > about what the parameters or functions did. Even the largest software > company in the world does not always get their documentation (or > software) right so I would not set the bar too high. I would advize > anyone reading any software documentation to keep the salt shaker > handy. > > At least a Jetspeed Wiki will give the "gurus" a place to correct any > misinterpretations or erroneous information which is better that the > current state of nothing. If the gurus take even the smallest amount > of interest in this, I am confident that the information can be > pretty good pretty quickly. Jetspeed is still a tool for pretty > sophisticated people so we should not get a lot of gibberish written > even by the newbies. > > > Ron > > -----Original Message----- > From: Ken Gunderson [mailto:[EMAIL PROTECTED] > Sent: Friday, April 30, 2004 10:36 AM > To: Jetspeed Users List > Subject: Re: Documentation > > On Friday 30 April 2004 07:35 am, Ron Wheeler wrote: > > I have some mindmaps that we generated in our first attempt to get > > something going in Jetspeed. > > It is a very complex environment with lots of pieces. It you have > > never worked with any of the underlying technologies, it is > > difficult to keep track of what each piece is and where the pieces > > touch. The names are particularly helpful;-). > > > > The tutorial was interesting but raised more questions than it > > solved. The construction of the old tutorial did not seem to follow > > very logically from the distribution jetspeed jar. As I recall, it > > appeared that files were in different directories and some files > > had been consolidated or restructured > > There seemed to be templates included in the demo which had been > > replaced by "prefered" methods in the documentation. > > > > I would have been better off if the time spent on creating the > > tutorial had been spent on writing documentation. > > I know that Apache is capable of writing good documentation. I use > > the HTTP server and Tomcat. They have pretty good documentation. > > > > A Wiki would be a good start and would allow the ignorant to at > > least document our misconceptions. The gurus could have a good > > laugh and a place of correct us. > > [mondo top posting snippage..] > > My personal view is that wiki's kind of suck for this sort of thing > becuase you have very minimal quality control. Wiki's frequently > become disjointed collections, e.g. person #1 started a node "here", > but person #2 didn't see it and starts onother node on very similar > topic "there". Additionally, with Wiki's you have no guarantee that > the author actually knows what they're talking about even if they > might have the ability to sound like they do. As a sysadmin who uses > and evaluates numerous open source tools, I've had to comb through > mor than a few wiki based documentation projects. Without some > management and oversight, they rapidly deteriorate into real pita's. > > That said, a little bird told me that Bluesunrise does have wiki > capabilities. With Jetspeed 2 looming on the horizon, however, I > suspect investing a whole lot of time in Jetspeed 1 documentation > isn't too high on the list of priorities. I think the Jetspeed 2 > group has someone dedicated to working on docs, but maybe Scott, > Jeremy, David,et.al can comment?? > > My $0.02
Arrggghhh!! Bloody top posters....;-p See important key closing sentence of paragraph 1;-) Also note opening sentence of paragraph 2 >;-D I think there is some debate w/in ASF regarding the use of wikis. I'm pretty sure there have been some issues in the past in regards to some critical remarks that were posted on one of the subproject wiki sites that left a bad taste in the mouths of some higher up types. I could be full of malarky though. That's the chance you take;-) -- Best regards, Ken Gunderson GPG Key-- 9F5179FD "Freedom begins between the ears." -- Edward Abbey --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
