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]
