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
What does it do, what’s the input, what’s the output.
If the README is too long, include a content section so that the user can jump around the README quickly.
- Hyperlinks to pre-requisites (websites)
- Hyperlinks to a separate README about installation procedures.
The first thing a new user will look for is an example.
- Always include some examples code and data so that people can run out of box and get a sense of how to use your software
- In README, include a ‘Quick Run’ or similar section to help the user run these example codes.
- If there are multiple examples, describe them in separate markdown file and link to them with hyperlink
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.
python ec2run.py -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.
If there is any.
Cut down unnecessary options
Too many options can be intimidating.
To make the README concise, use hyperlink whenever you can, especially for:
- Referring to a file in the repo
- Giving examples
- Prerequisites (link to the software’s website so that you don’t need to explain)
Whenever and whatever you are enumerating, use bulletin points instead of a complex sentence.
- Avoid having any line that is extremely long. Use ‘' to split long bash command into shorter ones lines for example.
- If the block is for demonstrating the usage of a docker, remember to include
docker pullso that the user always use the latest distribution
’##’ for section header and ‘####’ for subsection header seems to be good enough.