Turbine Documentation Project

The Turbine Documentation Project is the process of documenting Turbine, inside and out, for the user community. Opensource projects live and die by their community participation, as a software project is more than just source code, other components such as documentation have an important role in the process. As Software Engineers tend towards the habit of communicating in code, documentation is often skimped on, which can alienate the new or less experienced user. This component of the Turbine project will formalise the common and shared knowledge of the Turbine community into documentation for Software Engineers, Students, Hobbyists and interested passers-by alike. This however requires participation from all members of the Turbine User community.

What Can I do to Contribute?

Turbine can always improve it's documentation, there are many area's that always need attention;

  • Correct errors.
  • Correct spelling mistakes.
  • Replace out of date information.
  • Improve existing documentation.
  • Add new documentation.

There are more specific and immediate documentation needs in the TODO section below. If you are looking for an aspect of Turbine to start learn and document immediately, the ToDo is a good start. Documenting has the added advantage, that it is an excellent way to learn Turbine in detail and become an advanced Turbine user!

Documentation ToDo List

  • Fix spelling and grammatical errors.
  • Turbine and Security - There needs to be more documentation on Security management.
  • Turbine and LDAP - Security with LDAP
  • Turbine and JavaScript - Loading JS files through ContentURI
  • Turbine and JSP - Needs JSP examples.
  • Turbine and Python - Needs Python examples.
  • Turbine and Frames - Needs to be in its own document.
  • Screens and Actions - How the Default Screen and Action work.
  • Pull Howto
  • Torque Howto - including OM description
  • Intake Howto
  • Advanced Criteria - needs more description of comparitors and Criterion.
  • Services - All the services need documentation.

TDK Howto - Howto or tutorial describing initial app to creating your own schema, OM/peer classes, business objects through to Velocity templates.

Plus more .....

Website Documentation

The website documentation is the main component outside of the source code and javadocs. If there are ommisions on the website that you think need to be documented or written in, please go ahead and do it.

Turbine and TDK Feature Documentation

Turbine is a complex system with numerous features The features that make up Turbine all need documenting.

Turbine and TDK Internal Workings Documentation

How the components at the source level work, such as the Assemblers, Services, Actions and Screens, Connection Pooling etc.

Turbine and TDK Tutorials

How to use Turbine with other technologies such as JSP, JBoss etc etc How to use Torque, how to get a tdk project up and running. How to use the objects in Turbine for your projects such As Peers and Criteria.

Filtering Mailing Lists

Monitor mailing lists for common discussions and modify into a format that is sutiable for the Turbine Website and xdocs directory, plus adding a few choice comments. From there it can be improved.

Javadocing Source Code

Javadocing the source code where it is missing, incomplete or can be described better. As this is an opensource project the source code is open to all who wish to view it, having well documented, clean, understandable code is important.

Getting Started

To get started, read all the current documentation and find an area that you know a bit about. If that area isnt covered, you can improve Turbine by documenting it. Write up the document, no matter how skeletal and email it to the Turbine-Users-List, making sure your are subscribed first. All documentation of any kind is greatly appreciated.

The documentation is maintained as XML in the jakarta-turbine-project/xdocs directories, and is transformed to HTML for the website documentation.

Building the Docs

To build the HTML docs you need to check out the jakarta-site2 project from CVS.

You will also need all the Turbine sub-projects, as they are built automatically by Turbine's site module.

  • jakarta-turbine-2
  • jakarta-turbine-3
  • jakarta-turbine-torque
  • jakarta-turbine-fulcrum
  • jakarta-turbine-tdk
  • jakarta-turbine-site

When building jakarta-turbine-site, the generated documentation from all other repositories are copied to the jakarta-turbine-site/docs/ directory, providing one comprehensive set of documentation for the website. Run the build as follows:

ant docs

This will transform all the XML files in the jakarta-turbine-project/xdocs directories into HTML files in the docs directory. Validation errors may be thrown while processing, and will provide a line number for the XML file where the markup is incorrect. Usually, the cause of the error is something minor like an unclosed tag, unescaped XML entity, or a spelling error in a tag.

If you are a committer, don't forget to update the web-site.
Make sure your umask is set to 002!