Writing a README for a project
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
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.