Documentation Roadmap

We are working very hard to improve Turbine's documentation. Our weakest area is introductory material for new users. Currently, the best resource is the turbine-user mailing list. Although almost every question has clear answers found in the list archives, it is time-consuming to find them.

Below is the list of documentation items we are working on listed in order of priority from greatest to lowest. We need help with them all!

• Improve the presentation of our current documentation
• Turbine 2.3 Release Changes
  • Describe how Turbine uses Avalon (there is a basic service document, but furtehr details on creating services would be welcome).
• Quick Start Tutorial
  • Based on a simple sample application
  • Should most likely involve META
  • Currently in the wiki at Turbine2/Tutorial
  • When stable, move it to xdoc and prepare a release
• Complete User's Guide
  • Currently in the wiki at Turbine2/UsersGuide
  • Eventually in Xdoc, Forrest, or some other format
• Turbine Architecture Diagram
  • High level diagram of Services, Layouts, Navigations, TurbineServlet, Action, Screens, etc
  • Should be a picture showing distinct layers
• Clear Road Map of the Turbine Project
  • Future Features and Enhancements
  • The future of Fulcrum
  • Currently in the wiki at Turbine2/Development

Our Documentation Has Three States

1. Infancy: A document becomes nascent in the Wiki as an empty or sparsely populated page. At this point, people continue to add and revise the content until it becomes mostly stable and unchanging.
2. Stability: Once the document has reached a stable point, it is converted into the xdoc format and injected into the site or core modules at the subversion repository.
3. Maturity: As changes to the Turbine Framework are made, the documentation is updated and improved via xdoc patches from the bug tracker.

How You Can Help

Now that you know what we are working on, you need to know the best ways to help. Content is farmed and stabilized on the Turbine Wiki until it is stable enough to become official documentation. Additionally questions are answered and re-answered on the turbine-user mailing list. You can help the Turbine Documentation effort by:

• Editing The Wiki Content: Mature and stabilize the information on the Wiki.
• Filtering The Mailing List: When you see something float by on the mailing list that should become part of the official, please convert it into the appropriate xdoc format and submit it as an issue in our issue tracking system.
• Creating Xdoc Patches: If you find a typo, mistake or overlooked information in the official documentation, please create an issue in our issue bug tracking system.

Getting The Documentation Source And Making A Patch

1. Get The Source: Check out the latest source from the Turbine subversion module. You can learn about the Turbine repositories on the download page. The Turbine documentation resides in the turbine-site tree:

   svn checkout http://svn.apache.org/repos/asf/turbine/site

2. Build The Site: The documentation is built using Maven, with the following command:

   maven site:generate

   Afterwards, you should get something like:

   BUILD SUCCESSFUL
   Total time:  20 seconds

   You will find the built HTML in $PATH_TO_MODULE/target/docs.

3. Make Your Changes: The docs are written using the Anakia Xdoc format, which you can learn about here. The source files are found in the $PATH_TO_MODULE/xdocs directory, each xml file corresponding to the generated html file. Menu information is found in the navigation.xml files.
4. Make A Patch:

   svn diff  > name_of_patch.patch

5. Submit Your Changes: If you have a patch, log in to our issue tracker and create a new issue.A project committer will approve the patch and apply it, or let you know if something should be changed.
6. Thank you for helping out!