Documentation Guidelines

We know what volunteering is like, so we want to make it as efficient for everyone as possible. Here are the rules of the road for contributing documentation to the project.

The Docs are as important as the code itself. How is anyone going to use Wheels if they can't learn how to? And the great docs by Allaire/Macromedia/Adobe are a big reason why you've always loved ColdFusion, right?

Steve, Our Persona

In hopes of keeping everyone in the same spirit, let's give the narrator of the website and documentation the name Steve. Let's pretend that we're Steve when writing in order to keep things interesting, friendly to our audience, and consistent.

Here's a description of Steve's persona. Being a Wheels nerd, you'll probably find himself easy to relate to.

  • Snarky and not afraid to color outside of the lines of formalities a little bit.
  • Has a dry sense of humor but is still funny.
  • An OOP and MVC know-it-all, but also very willing to explain things in simple terms when needed.
  • Tried Fusebox and Mach-II a few years ago and never quite "got it."
  • Giddy about the simplicity and elegance of Wheels.
  • The kind of guy that you'd like to grab a beer with.
  • The only other guy in meetings that you attend that "gets it" and doesn't annoy others or waste time.

Process

All documentation should go through these processes. Let's not be a bunch of cowboys like MySpace developers!

  1. First off, let the Discussion Group know what you're planning on doing! We would hate for you to spend hours writing a document that someone else is also working on. Plus the group would be glad to help out answering any questions that you may have.
  2. Draft content in the Google Code Wiki. Access to edit Wiki articles is public.
  3. Label the Wiki article with the "chapter" tag for Reference Guide chapters and the "api" tag for API documentation.
  4. Label the Wiki article with the version of Wheels that it applies to. For example, if an article was updated for the 1.0 release, make sure that the version tag is set to "1.0".
  5. Post a request to review the content in the discussion group.
  6. After you address any questions or issues that the group may bring up, a member of the core team will post the new documentation live on the website (if the Wiki entry applies to the current version). The core team member may also make minor stylistic edits to the content before posting as well. Please don't take offense to this; they're only trying to help!

Content Style Guidelines

Here's a description of the different types of documentation and general expectations. Let's ride in style!

Chapters in the Reference Guide

The Reference Guide contains narrative chapters about using the framework. It should contain a wealth of code samples and screenshots and should be written in clear, concise language.

Video Tutorials

Video tutorials should cover an area of Wheels that hasn't been covered in previous videos. Please publish the video in Flash or Quicktime format at a maximum width of 800 pixels. The core team will make the final decision on whether or not the video will be published on the Wheels site.

API Documentation

The API documentation should be very clear and concise. Let's keep Steve out of it for the most part. He understands.

Most descriptions of Wheels' functions should follow this general format, inspired by the CFML function reference in the ColdFusion 8 Live Docs.

Description

A concise description of what the function does. Also include any notes like what types of values that are supported.

Returns

Short description of what is returned from the function, if anything.

Function Syntax

functionName(argument1, argument2, [optionalArgument])

History

History of how function behavior changes from version to version of Wheels.

Of course, there will be exceptions to these rules, and we can trust that you'll use sound judgment before breaking them.

CFML Engines Supported

List of tested and supported versions of ColdFusion, Railo, OpenBD, etc.

Parameters

Parameter Type Required Default Description
argument1 string Yes N/A A description of argument1, including type and possible values if applicable.
argument2 string Yes N/A A description of argument2.
optionalArgument boolean No false A description of optionalArgument, including default behavior if applicable.

Usage

Narrative of common use cases for the function, with plenty of examples.