The Challenge

Creating a good website and set of project documentation for an open source project can be challenging:

Luckily, Velocity has a great web site and an excellent set of documentation. This note provides suggestions to keep the quality high while also taking advantage of the knowledge across the community.

Resources

Current Velocity documentation includes:

Other non-official documentation includes

Guidelines

Having said all that, here's a few simple guidelines for contributing and storing documentation:

  1. The software documentation (primarily the User's Guide and Developer's Guide) should contain a comprehensive overview of Velocity features. As new features are added to source control, these guides should be updated at the same time and stored in source control.
  2. The software documentation available on the web site should correspond to the latest released version of the software. This is as opposed to the latest docs in source control (which are available within the nightly snapshot along with the source itself).
  3. When possible, typos or errors in documentation for released versions should be fixed, stored in a source control branch, and updated on the web site.
  4. The documentation should be comprehensive, but should also offer recommendations and best practices when possible. As community opinion changes as to recommended approach (e.g. the move from VelocityServlet to VelocityViewServlet) the documentation should be updated to reflect this change in thinking.

  5. Each issue from the Issue Tracker that is resolved (as well as any other feature additions) should be logged in a Change Log (project documentation).
  6. The Wiki can be used for community contributions or frequently changing content. Examples include a FAQ, links to community articles and published articles/books. (Community articles can be on the author's web sites, or with their permission on the Wiki itself).
  7. The Wiki is a good place to keep developer-related info (which can benefit from group editing and review). This may include Road Map, issue priorities, and archiving of debates over future architecture and direction.

Get Involved

Want to help? Here's what you can do:

  1. Write an article about your experience with Velocity and put a link to it on the Wiki.
  2. Update the Wiki with a link to your Velocity-based web site or software.
  3. Contribute a FAQ entry in the Wiki based on your experience or an exchange on the mailing list.
  4. Fix a typo or mistake in the project documentation and submit a patch via Bugzilla. Or fix a typo in the Wiki directly.
  5. Create a new software feature and submit it with documentation in Bugzilla.
  6. Offer constructive feedback on these guidelines (or the documentation in general) on the Velocity mailing lists.