Rails Guides Conventions

Prologue

Each guide should start with motivational text at the top, telling readers what they’ll learn. ( Example – Routing Guide )

Generic Remarks

Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the recommended idioms in edge (which is the version we are documenting), reorder sections to emphasize favored approaches, etc. The documentation should be a model for best practices and canonical, modern Rails usage.

Try to make your examples fit the boxes in the page design—wrap comments and long method calls, shorten code, etc., as needed.

The proper spelling of Rails components is as separate words: “Active Record”—not camel-case. Please follow that convention. There’s lack of unanimity in Rails books, but we verified this with David.

Titles

The title of every guide uses h2, guide sections use h3, subsections h4, etc.

Capitalize all words except for internal articles, prepositions, conjuctions, and forms of the verb to be:

  h5. Middleware Stack is an Array
  h5. When are Objects Saved?

Use same typography as in regular text:

  h3. Brief Note About +Test::Unit+
  h6. The +:content_type+ Option

Fonts

For the sake of coherence, Rails Guides follow the same typographic conventions as the API documentation:

Fixed-width font for method names, literals like nil, false, true, self, symbols, and method parameters.

  Validations such as `validates_uniqueness_of` are one way in which models can
  enforce data integrity. The `:dependent` option on associations allows models to
  automatically destroy child objects when the parent is destroyed.

When “true” and “false” are English words rather than Ruby keywords use regular font for them:

  If you set the +:accessible+ option to true, then mass assignment is allowed
  for this association.

Fixed-width font as well for constants, in particular for class and module names.

  A migration is a subclass of +ActiveRecord::Migration+ that implements class
  methods: +up+ (perform the required transformations) and +down+ (revert them).

  To get started make sure +Base.perform_caching+ is set to true for your
  environment.

Fixed-width font also for filenames:

  For example +20080906120000_create_products.rb+ should define +CreateProducts+ and
  +20080906120001_add_details_to_products.rb+ should define +AddDetailsToProducts+.

Textile

Guides are written in Textile. There’s comprehensive documentation here and a cheatsheet for markup here.

HTML Generation

Prerequisites: erubis & i18n gems

To generate all the guides just cd into the guides directory and execute

  # generates the HTML of all guides
  bundle exec rake generate_guides

This will generate all of the docs and store them in the guides/output directory.

To process my_guide.textile and nothing else use the ONLY environment variable:

  # generates the HTML of "my_guide.textile"
  bundle exec rake generate_guides ONLY=my_guide