Rails applications and ruby gems should have a README that gives the reader a quick overview of the project. Its size will vary as projects differ in complexity, but there should always be some introductory prose for a developer to read when starting on it.

Purpose

Growing Rails Applications in Practice

Check out our e-book. Learn to structure large Ruby on Rails codebases with the tools you already know and love.

• Introduce design conventions for controllers and user-facing models
• Create a system for growth
• Build applications to last

Read more Show archive.org snapshot

That's already the main purpose of a project README: Give a new developer a quick overview of the project. In sketching this outline, the README should notify the reader of any peculiarity he needs to know of.

Remember that in a few months, you'll be a kind of "new developer" yourself as you forget more and more details about the project. Writing a README is helping your future self, too.

Do

• be concise
• keep the README short, around 100 lines. It should be an abstract of the project, not a novel about it.
  • a huge README is hard to skim and discourages reading it
  • if it gets too large, try to extract parts to the areas they describe
• remember that a README is documentation, and documentation is complementary to code

Don't

• don't describe details of certain classes. Class documentation should be written atop the class file.

Structure

I suggest the following outline for a Rails project's README, using the very readable Markdown language:

# App title

Describe the whole project in a few sentences to a few paragraphs, just as you
would explain it to your fellow developer. What is it actually, what was it
built for, who is using it, etc


## Architecture and models

Give a quick overview of the few core models and how they interact. Do not go
into detail – class documentation should be written atop the class file. Just
impart the very basics to grasp the application model, so a new developer knows
where to dive in.


## Development

Describe how to get started with the project. Document employed 3rd party
services and how to use them, how to start a development server – just about
anything that a new developer needs to know.


## Peculiarity X

Add a section for each special concept in the application, e.g. a CDN and what
it is used for, that icons are rendered from a custom icon font and how to update
it, that all posts are created from an importer, that there's a web UI *and* a
JSON API *and* an embeddable component.

Make the reader aware of a peculiarity, but remember to keep it short. Details
should be documented in the respective area.

Examples