Notes on writing a good GitHub README

Guideline of design

Design the structure from user’s point of view. Make the structure clear. Be concise in each section.


What a good structure contains

High-level description

What does it do, what’s the input, what’s the output.

Content (optional)

If the README is too long, include a content section so that the user can jump around the README quickly.



The first thing a new user will look for is an example.

Highlight the steps to prepare for running

Keep each step concise. If a step is too long, hyper-link it to a separate README.

Introduce interface with parsers

Use parsers in your software to deal with input options so that you can reuse them (therefore save space) when introducing the interface.

For example:

python -h

positional arguments:
  mode                  Running model (GPU/CPU)
  connection            connection type (VPN/S3)
optional arguments:
  -h, --help            				show this help message and exit
  -a AMI, --ami AMI     				Target AMI (default ami-864d84ee for CPU mode, ami-763a311e for GPU mode).
  -s SUBNET, --subnet SUBNET    		VPN (?) subnet.
  -i ITYPE, --itype ITYPE   			Instance type (default r3.xlarge).
  -k KEYNAME, --keyname KEYNAME			Keyname (default starcluster; credential file overrides this).
  -r REGION, --region REGION 			EC2 region (default us-east-1).
  -p PRICE, --price PRICE 				Spot bid price (default 0.34).
  -u USER, --user USER  				User (default is $USER).
  -e EMAIL, --email EMAIL				Email address to send and get notification
  -n SPLITSIZE, --splitsize SPLITSIZE	Number of commands per instance (default 1).
  -b BUCKET, --bucket BUCKET 			The S3 bucket for data transfer (for S3 mode only)
  -ru RUNNAME, --runname RUNNAME		The S3 runname for data transfer (for S3 mode only)
  -v VOLSIZE, --volumesize VOLSIZE		The size (in GB) of hard disck (/scratch) added to each EC2 instance (default 500)


A more systematic introduction of the usage than the ‘example’ section which contains out-of-box running cases with no flexibility.


To make it more legit.

Paper citation

If there is any.


Good practices

Cut down unnecessary options

Too many options can be intimidating.

To make the README concise, use hyperlink whenever you can, especially for:

Bulletin points

Whenever and whatever you are enumerating, use bulletin points instead of a complex sentence.

Code block

Font size

’##’ for section header and ‘####’ for subsection header seems to be good enough.