Programmers have been lamenting each others’ inability to properly document software for many decades. Some recent examples include:

• Tom Preston Werner’s call for README-driven development

  a beautifully crafted library with no documentation is also damn near worthless.

• Ted Nyman’s recent Basho Chats diatribe about software expressing itself poorly (video not yet uploaded)
• Peter Morgan’s eloquent Go issue report

  Is that all we want to do is explain bits of code, and its runningz what it does.. Hopefully there is a lot of coders looking at it cos we can auto gen documentation..

Powerful stuff. There’s been a corresponding surge in tools to assist in creating documentation. Some examples:

• Eric Holscher et al’s Read The Docs
• Ryan Tomayko’s ronn

Still I see repositories with READMEs like “Gathers and relays system metrics” (not to pick on anyone in particular, just an example) and ones that skip straight to installation instructions and licensing info. That’s bad.

The README is a project’s face to the world. It should tell the audience what the project does and what motivated its creation at a minimum. Not to belabor the already-well-made point too much further, I’ve created a tool for myself and others to help formulate a basic README when inspiration betrays us.

It’s called readmeme - and yet again, Richard Crowley helped me name it. It is apt. I hope it starts a meme of informative READMEs.

For more info on the project, check it’s README (get it?)