The Rails API documentation is generated with RDoc. Please consult the documentation for help with the markup , and also take into account these additional directives . 2 Wording Write simple, declarative sentences. Brevity is a plus: get to the point. Write in present tense: "Returns a hash that...", rather than "Returned a hash that..." or "Will return a hash that...". Start comments in upper case. Follow regular punctuation rules: # Declares an attribute reader backed by an internally-named # instance variable. def attr_internal_reader(*attrs) ... end Communicate to the reader the current way of doing things, both explicitly and implicitly. Use the idioms recommended in edge. Reorder sections to emphasize favored approaches if needed, etc. The documentation should be a model for best practices and canonical, modern Rails usage. Documentation has to be concise but compre...