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.
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.
Should this thread be on the Turbine-User list or a separate Turbine documentation 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]
