README.md: History and Components

8 min readAug 13, 2015

So you finished writing your amazing opensource project, you are ready to publish it and make it public … But something stops you. If you are like me, then the infamous README.md is the last file you author.

Whenever I start a project README.md is one of the reason, if not the only reason, that makes me dubious about the project.
What to write here? How much is enough? Should I put this here? Should it go to another file? Authors? Change log? These are some questions the pop into my head in each project.

If you also have these questions, then read on, this article might be just for you.

Readme has multiple definitions, the best description I found is from Jargon file:

Hacker’s-eye introduction traditionally included in the top-level directory of a Unix source distribution, containing a pointer to more detailed documentation, credits, miscellaneous revision history, notes, etc.

History

The origin of the README file is not 100% clear. Some sources say that it originates from Programmed Data Processor (PDP -10) as early as 1974. Others state that it might even originates earlier than that.

A very early version of readme can be found in the form of readme.txt from a PDP-10 DECUS project dated 27th November 1974. This file contained information on how to operate the circuit analysis program for this specific PDP.

[README.TXT is the DOC file for SPICE/SINC/SLIC] This failsafe tape contains the circuit analysis programs:
SPICE SINC and SLIC
described in the Applications Software Bulletin Volume 4.

Another version, from 27th March 1975, also appear in a later PDP-10 DECUS project. This file contain even more cryptic operational instructions:

The files on this FAILSAFE tape constitute the UCI LISP system. They are for the most part documented in the UCI LISP Manual, available from the Department of Information and Computer Science at the University of California, Irvine, California.

Jargon file (1978), suggests the possible origin of the README name to be from the beloved Carroll’s Alice’s Adventures In Wonderland book:

When asked, hackers invariably relate the README convention to the famous scene in Lewis Carroll’s Alice’s Adventures In Wonderland in which Alice confronts magic munchies labeled “Eat Me” and “Drink Me”.

Other historical versions of README can be spotted in early versions of Unix. Spanning from July 1977 to March 1980.

Programmer’s Workbench, 1977, /sys/source/lex/README
Unix 7th edition, 1979, /usr/doc/README
First 32bit BSD, 1980, usr/doc/README

One other possible, and much earlier, origin of the README might even be before the 70's. This answer on Stackoverflow describe how possible earlier versions of READMEs were distributed as printed manuals that came along punch cards and mag tapes. Bellow is an interesting quote from the Stackoverflow answer:

The convention (of printed readme document) apparently also follows the old system in that with all the punch cards a “reem” of paper was attached with the statement README in caps printed on it, this had all of the instructions for use and loading of the punch cards into the system.

README file name

There are multiple known names for the readme file. Historically, the most common name README (from jargon file). The reason for the all caps name is that in ASCII systems capital letters comes before small ones. This would make README file sort before all other source code files, which makes it more prominent for the developer.

Other famous forms are README.md, Read.me, Readme.txt, Readme.txt and Readme.1st.

Components

There are multiple sections and components that are normally part of a good README file. The sections and their length depends on the project type.
Bellow is a description of the most common sections and components and an example from a popular opensource project.

The Project name

Name of the project. This section might contain the project logo.

Example from Robo Guice:

Badges and Emblems

After the project name normally comes the list of emblems the project uses.

Some of these emblems:

Build (CI) (Travis, CircleCI, Teamcity)

Code Coverage (Coveralls)

Cocoapods version (cocoapods)

Android Arsenal (Android Arsenal)

Pip version (pypi)

Code analysis (Code climate)

This github repo contains a huge list of badges with their description.

Project description

A short description of the project, including the purpose and the reason for creation. This also might include the main use case for the library or cli tool.

Example from Reactive Cocoa:

Installation

Steps to download and install the opensoure tool on your machine, in case it’s a cli tool. Or if it’s a library, steps to install it in your project
If the installation instructions are long and complicated, they are more fit for an INSTALLfile.

Example from React.js:

Example usage

If the project is a library, this section includes a very short an concise example on how to use it.

The code example is not the documentation, this normally is a very short explanation of a very simple example of using the code.
For cli and other kind of applications, this section include a description on how to use the app.

Example for a library taken from Glide:

Example for a cli tool taken from Bundler:

Reason for creation

Why was the project created, what problems does it have to solve. What are other ways to solve the problem, and how this library compares to them.

Example from FlatUIKit:

Documentation

The documentation section vary drastically based on the project type; if the project is a library, the documentation might be simple and containing a link to a separate website or wiki. However, If the project is a cli tool, the documentation describes the main commands and subcommands and the most useful cli flags.

Some of the library examples:

If the project is small enough, documentation for all the public API might be included in this section. In case the project is relatively big, a link to the documentation or the WIKI might be included here. Some library projects might include runnable samples for the developer to download.

For example, the following libraries has a very short or no documentation section, they however contain a link to an external documentation source:

Authors

List of authors and contributors. The list also contains a link to the contributor profile or email.
When the list of authors gets too long they normally get moved to the AUTHORS file.

Example from OAStackView:

License

Information about the license use or a link to LICENSE file. If the project is using other subproject with different licences, a list of these licences may be included.

Example from Ruby on Rails:

Change log

The list of changes introduced in each version or a link to a more comprehensive change log file.

Example from CodeIgniter:

Contributing instruction

Description on how to contribute. For example, this may contain instruction on how who to contact, how to write specs or unit tests, what level of documentation to write, and what kind of project high level architecture to adhere to.

Example from PHPMailer:

Tests

Information on how to run the test suite.
For example from jquery:

Credits

List of people and sponsors to thank. If the credits gets too long, it might be moved to a CREDITS file.

Example from Showdownjd:

Known bugs

A list of the most user/developer affecting known bugs. This list might include a workaround to solve some of the bugs.
If the list of bugs gets long, it will be moved to a separate file or wiki.

Example from MarkdownEditing:

How to compose a good Readme

There is no real universally accepted form for a good readme. It highly depend on the project type.

For example, bigger projects adapt the very short readme file, the readme typically only contains links for a proper website and/or for a wiki page.

Some of these examples are:

For shorter projects, the readme tend to be longer, with more or all of the information about the project. Some of these readme examples:

For small to mid sized projects the following are short and sweet Readme templates:

Jxson README.md template
Zenorocha A template for Github READMEs (Markdown) + Sublime Snippet
Repat README-template

Personally, I prefer Zenorocha (A template for Github READMEs (Markdown) + Sublime Snippet) template, it contains some of the most useful README file sections. These sections are normally enough for a short and succinct readme file.

Readme Driven Development

There is no doubt that the README file is a very important file. It is so important that Tom Preston-Werner, github co-founder and former president, suggested a development flow driven by the README file.

Write your Readme first.

He goes more deeply into how RDD (readme driven development) differs from DDD (documentation driven development). In his article he describes the benefits of using RDD. For more info refer to his original article here.