In open source software, the more users there are of a project, the better it is for everyone. With more users the most common use cases will be discovered, implemented, and well-tested. A well-used project is a healthy project.

To encourage new users to consider your project, it's important to provide a smooth on-ramp for a common use case so that a prospective user can get value from it without having to invest much time. This makes it easier for the user to decide whether the project will be a good fit for their needs rather than feeling overwhelmed by information overload and moving on to evaluate another project.

Choose a Good Use Case

A good use case, sometimes called a "Hello World" application, meets the following criteria:

  • It's something that many people would want to do.
  • It's easy to do with your project and would be challenging to do without it.
  • It's simple and easy to understand.
  • It doesn't require the prospective user to learn anything (non-trivial). Keep your eye on this one. If the prospective user has to learn something before they have a reason to care about your project, you may lose them.

Pave the Way with your README

Put care into writing your README file; it is the entrance to your project. If people can't get through your entrance then it won't matter how elegant your code is or how much effort you put into writing it.

If your project has a well-formed README file then it will be valuable to other people. If it doesn't, chances are it will be valuable only to you. A well-formed README should have the following elements at the top before anything else:

  1. the name of the project, e.g., Eris CLI
  2. a short description of the project, e.g., Eris is a tool which makes it easy for developers to build, test, manage, and operate distributed applications.
  3. installation instructions (make a Herculean effort to keep these as short as possible. The ideal is a single line, e.g., $ docker run -it eris/cli).
  4. a short, line-by-line example of how to make it do something uniquely valuable, preceded by the answer to the question, "Why would I care?"


I chose the Eris project for this sample README as a bit of a challenge for myself because I'm currently working on it and because it's not obvious how to craft a good explanatory use case for it. Notice how the one below is not necessarily something that many people would want to do but it does illustrate how to do something easily with Eris that would be difficult to do otherwise. Also, while it's not easy to understand it is simple.

Eris CLI

Eris is a tool which makes it easy for developers to build, test, manage, and operate distributed applications.



  • Docker >= 1.7.1
  • Go >= 1.4.2
$ go get
$ eris init

Quick-Start Example

DNS servers are extremely important to the basic functioning of the Internet and it's imperative that they are reliable and resilient. Using a blockchain to back a DNS server can dramatically increase its resistance to accidental and intentional corruption. Setting up such a DNS server is hard but is one of the things that Eris makes easy. To create a DNS server backed by a blockchain, type the following commands into a shell:

$ mintgen random 1 mychain
$ eris chains new mychain --dir=mychain
$ eris services start mindy --chain=mychain
$ addr=$(mintkey eris ~/.eris/blockchains/mychain/priv_validator.json)
$ export MINTX_PUBKEY=$(eris-keys pub --addr=$addr)
$ data='[{"fqdn":"", "type":"NS", "address":""}, {"fqdn":"", "type":"A", "address":""}]'
$ mintx name --data="$data" --amt=1000000 --fee=0 --sign --broadcast --wait

Now test it by looking up the IP address for

$ server=$(eris services inspect mindy NetworkSettings.IPAddress)
$ dig @$server

Automated Test

Create an automated test which exercises the example and make sure it runs every time you push to master. If the test ever fails, respond the way that Amazon would if its front page went down. The rest of the site doesn't matter if users can't get in the front door. Freak out immediately and work on nothing else until it passes again.

Treat your Words as Code and Optimize for Performance

If you want to include something else in the README, that's fine but make sure it doesn't precede any of the above (don't block your entrance). As you write the README, think of an imaginary value meter that represents the value it is creating for the reader. Ideally the value increases to a high level quickly and stays high. Words are necessary to create value, but every single word in the README is a cost to the reader. It's worth repeating: The act of reading words in your README is a performance cost for the reader. For this reason it's paramount to be concise. You can think of each word as being like a megabyte in a Docker image. It's worthwhile (and necessary!) to download megabytes in order to get the value from the image but the downloading of the megabytes is a cost. Don't make your README (or your Docker images) unnecessarily expensive to read/download.

When to Create your On-Ramp

So now that you surely agree it's a good idea to create a smooth on-ramp, you'll do it as the last step after finishing the rest of the project, right?

In 1855 two men in Ohio constructed a small town in anticipation of a railroad that they were hoping would be built in the area. They named their new little town "Rawson" after the president of the railroad company, hoping that would influence him, but no locomotive came for 17 years. (Rawson and the Railroads)

It's better to build your railroad before your town. Start with a good use case that's functioning and attracting users and then build on your codebase from there.