Writing a README for a project

Updated . Posted . Visible to the public. Repeats.

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.

Examples

Dominik Schöler
Last edit
Arne Hartherz
License
Source code in this card is licensed under the MIT License.
Posted by Dominik Schöler to makandra dev (2017-12-05 10:57)