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, and method parameters.

  # Copies the instance variables of +object+ into +self+.
  #
  # Instance variable names in the +exclude+ array are ignored. If +object+
  # responds to <tt>protected_instance_variables</tt> the ones returned are
  # also ignored. For example, Rails controllers implement that method.
  # ...
  def copy_instance_variables_from(object, exclude = [])
    ...
  end

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

  # If <tt>reload_plugins?</tt> is false, add this to your plugin's <tt>init.rb</tt>
  # to make it reloadable:
  #
  #   Dependencies.load_once_paths.delete lib_path

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

  # Returns the classes in the current ObjectSpace where this module has been
  # mixed in according to Module#included_modules.

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:

  # This can also be set as a configuration option in <tt>config/environment.rb</tt>:
  #
  #   config.action_mailer.default_url_options = { :host => "example.com" }