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 -- 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] --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
