The Ruby on Rails experts
Logo_144 ClearCove Software, Inc. Rails Recipes

Pretty much any serious Rails project will require some kind of documentation that reminds us of:

  • How to run a manual database query for reporting.
  • Why we chose one gem over another.
  • The thought process for developing a complex piece of functionality.

We prefer to have this documentation in the app and under version control.


  • Text files in doc/.
  • Formatted with Markdown.
  • Tracked in git.
  • Ongoing development notes go into doc/dev_notes/. They are prefixed with a date stamp for chronological sorting.
  • How-tos for repetitive tasks go into doc/how_to/. They can be text documents, ruby source code or SQL statements. Use .md, .rb, and .sql extensions accordingly.

Here is an example doc folder:

+ [app_root]
  + doc
    + dev_notes
    + how_to

Once the dev_notes grow too large, we move older ones into doc/dev_notes/archive to keep our working set small and manageable.