Arg!!!! Please ignore the first set of comments. I started moving them inline with the previous message and forgot to delete them before sending the email.
-------------------------------------------- Quinton McCombs NequalsOne - HealthCare marketing tools mailto:[EMAIL PROTECTED] http://www.NequalsOne.com > -----Original Message----- > From: Quinton McCombs > Sent: Tuesday, March 18, 2003 2:17 PM > To: Turbine Users List > Subject: RE: Wiki Turbine 2 User's Guide Outline > > > George, > Thank you for offering to help out with the documentation. > We certainly need all of the help that we can get especially > from people with technical writing experience. > > The Wiki does have a few drawbacks as you pointed out. The > main reason that we are doing this on the Wiki first is to > gather content. As the content starts coming together, we > will organize into the xdoc format that is used to generate > our web site. > > None of this is set in stone as of yet. The primary focus > right now is simply getting content and figuring out how we > will organize everything. If you have any suggestions for > another medium to get started with, we welcome your comments. > > Ir is not written in stone that xdoc will be the final format. > > -------------------------------------------- > Quinton McCombs > NequalsOne - HealthCare marketing tools > mailto:[EMAIL PROTECTED] http://www.NequalsOne.com > > > -----Original Message----- > > From: George Allaman [mailto:[EMAIL PROTECTED] > > Sent: Tuesday, March 18, 2003 1:32 PM > > To: Turbine Users List > > Subject: RFC: Wiki Turbine 2 User's Guide Outline > > > > > > I'm a Turbine newbie, so please forgive if I'm going over covered > > ground, but I'd like to get involved in the Turbine documentation > > effort. I did a few years as a tech writer before going into > > development. > > Thank you for offering to help out with the documentation. > We certainly need all of the help that we can get especially > from people with technical writing experience. > > I am certainly willing to explain anything about Turbine (for > the areas where I have intimate knowledge) in order to help > this documentation get written. I am sure that any of the > other developers would be willing to do the same. > > > I totally agree with the statements about poor organization > > of existing > > Turbine documentation. I struggled getting started, and big > thanks to > > those who helped me. > > > > As an example, the "Getting Started" stuff I could find is > > out of date - > > both that in the TDK and that online. This is a big barrier > > to those who > > want to do a quick and dirty proof-of-concept app of their > > own (not the > > "newapp" sample supplied with the TDK) to evaluate whether or > > not they > > want to continue with Turbine. Most would probably say, > "This is too > > time consuming - I'll just throw money and my soul at Bill Gates." > > > > Chris's existing Wiki outline: > > > http://nagoya.apache.org/wiki/apachewiki.cgi?JakartaTurbine2UsersGuide > > is a very detailed and well thought out start but missing a > "Getting > > Started" section which I think is critical. > > > > I like the idea of an online doc but I don't like the idea of > > not being > > able to print it in its entirety in one action. I don't think Wiki > > supports this. > > No. One of the drawbacks of the Wiki. > > > I also am not sure that the Wiki structure will be a big > win over the > > existing mail list. With Wiki you can zero in on your topic > > of interest > > quickly from the TOC, but having done this the material won't be > > structured in any particular way because of the lack of > > hierarchy. This > > doesn't seem materially better than simply doing an archive > search on > > the list. Archive searches will find you the answer you need if it > > exists, but you spend a long time trying ferret them out of > > the masses > > of related information that's useless for the specific answer > > you need. > > > > I think there is no substitute for a human organizing the > > material in a > > hierarchical way and in the order that a new user needs to > > approach it. > > An index is invaluable. > > > > If this is impossible or not feasible due to the distributed > > nature of > > Turbine development efforts, Wiki may offer a marginally > more usable > > view of the documentation, but I'm not sure if it is an order > > of magnitude. > > We can fix all of this. The goal right now is to simply > start gathering content and figuring out how to organize it. > This much can be done fairly quickly on the Wiki. It also > allows everyone to make changes without having to submit patches. > > I think that once we get the outline nailed down and start > getting some good content developing, we can start moving > into another format. The Jakarta standard is the anaconda > (or xdoc) format. This is generally what all of our > documentation is written in. This format is then used to > generate the HTML pages of our site. > > We are not locked into this format. If we start going down > this road and we discover the format to be too limiting, we > are free to change to any format that we want. Docbook has > already been mentioned as a possibility. > > I agree with you 100% on the need for hierarchy. Being able > to search would be a nice feature as well. I would also like > to see us be able top publish the manual to HTMl for the site > and also PDF for downloading. > > > Should this thread be on the Turbine-User list or a separate Turbine > > documentation list? > > This thread should really be on the Turbine-dev list. > > > From: Chris K Chew <[EMAIL PROTECTED]> > > > > > I have an idea. I think some of the documentation that > > already exists > gets overlooked by newcomers because it's > > organized poorly. As an > example, the TDK how-to has some > > important basics about developing an > app with Turbine, yet > > people don't read it because it's under TDK on the > site. > > I'm waiting for a response from Michael C. Starkie regarding > > the > thread "newbie create new table" to verify this. > > > > I suggest we reorganize the docs, although I don't have a > > specific > recommendation. > > What do you think? > > > > Definitely! > > > > Humberto Hernandez was also speaking earlier this week about > > improving how we position Turbine, which is certainly > > something we must do. > > > > I pretty much envision the user's guide as eventually > > replacing the majority of the Turbine documentation. MySQL > > is a good example, in my opinion. A single reference manual > > will increase the likelihood that it remains up-to-date by > > keeping all the information in one place. > > > > A manual won't really cater directly to people perusing the > > site looking for a new framework (although having one will > > help position Turbine as having good support and a strong > > community). Consequently, we would still need additional > > information geared towards positioning Turbine for potential > > new users. > > > > With these in mind, the areas of documentation might be > > something like: > > > > *Introductory "Why Use Turbine" Information > > *Quick Start Tutorial (Build a sample app) > > *Maven-generated Information (Changes, javadoc, etc.) > *Complete Manual > > (Concepts, Migration, Troubleshooting, Known Issues, etc. > > SEARCHABLE) > > > > Any thoughts? > > > > > > Thanks, > > Chris > > -- > > George Allaman > > Denver, Colorado > > 303 466 2114 > > > > > > > --------------------------------------------------------------------- > > 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] > > --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
