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
- 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
Here is an example
+ [app_root] + doc + dev_notes 20121003_choosing_a_gem_for_pagination.md 20130511_dynamic_navigation_in_a_jekyll_site.md + how_to create_demo_data.rb deploy_to_production.md query_activities_longer_than_24_hrs.sql update_git_submodules.md
Once the dev_notes grow too large, we move older ones into
to keep our working set small and manageable.