Each guide should start with motivational text at the top, telling readers what they’ll learn. ( Example – Routing Guide )
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.
Try to make your examples fit the boxes in the design, wrap comments, long method calls, just shorten stuff, etc. as needed.
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.
Use title case for
h2. Performance Testing Rails Applications h3. Performance Test Cases
and regular case for
h4 and below:
h4. Understanding the output h5. Wall time
For the sake of coherence we follow in Rails Guides the same typographic conventions of the API documentation:
Fixed-width font for method names, literals like
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 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.
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+.
To generate all the guides just cd into the
railties directory and execute
- generates the HTML of all guides
my_guide.textile and nothing else use the
ONLY environment variable:
- generates the HTML of “my_guide.textile”
rake guides ONLY=my_guide