Rails Guides Conventions

This document is work in progress

Prologue

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

Wording

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

The proper name of Rails components has spaces in between: “Active Record”. Please write them like that. There’s lack of unanimity in books, but we checked it with David.

Fonts

For the sake of coherence we follow in Rails Guides the same typographic conventions of the API documentation:

Fixed-width font for method names when they are alone, 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.

Regular font as well for constants and for method names qualified by the class or module they belong to.

  A migration is a subclass of ActiveRecord::Migration that implements two 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.

Normally constants would be written using a fixed-width font, but regular font is already used all over the
docs, so we just follow this convention.

Fixed-width font for filenames:

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

AsciiDoc

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

HTML Generation

Given Python and a recent version of the gem FooBarWidget-mizuho, just cd into the railties directory and run

  rake guides