Programming is hard, and we need all the help we can give one another to make it easier. I’m blown away when I find projects without readmes, or readmes that only provide a single, cryptic line describing the project, like “A better [other project].” How is a visitor supposed to know what to do with your project? From installation to usage to testing to contributing to licensing, your project needs documentation to be useful.
Readmes are the backbone of a project’s documentation. They’re a visitor’s first impression. How do you make them good? Pretty easily. A good readme covers this:
What Does the Project do?
First and foremost, inform visitors what your project accomplishes (or hopes to accomplish). This isn’t a sales pitch, just a description. Por exemplo:
Requests - Requests is an Apache2 Licensed HTTP library, written in Python, for human beings
Flask - Flask is a microframework for Python based on Werkzeug and Jinja2. It’s intended for getting started very quickly and was developed with best intentions in mind.
Express - Fast, unopinionated, minimalist web framework for node.
Each of these examples is minimal, straightforward, and helps you decide whether this project is worth your time. Many projects, including Requests, choose to include code samples to demonstrate their interface, or to briefly list differentiating features. Both help visitors determine whether your project solves their problem.
How Do you Install it?
Before a visitor can begin using your project, they need to get it. Show them how. List dependencies, and any instructions you’ll need to run to get the project. At a minimum, include terminal instructions. Express‘ entire “Installation” section, for example, is just one line:
$ npm install express
That line presumes that you have NPM installed, that you understand it’s a terminal instruction, and that $ indicates this is a BASH prompt, and thus should not be executed. So, it could be better, but it gets the job done.
If your installation instructions are particularly complex, or differ depending on your operating system, then break those differing instructions into multiple sections. CouchDB, for example, has three installation guides.
How do you use it?
This is the entree. “Usage” sections of readmes should detail the project’s features, interface, caveats, gotchas, tips, etc. Everything a stranger needs to solve problems with your project.
If, for example, your project is an API client (like Porc), you should enumerate every method of every class exposed by the client, along with what parameters they accept, and what they accomplish. This can get pretty lengthy, but welcome to writing usable software. The CouchDB client Nano, for example, includes a table of contents that lists every client method, with code samples showing the library in action.
If you find this section getting problematically lengthy, you can link to external documentation. Requests‘ readme’s “Documentation” section, for example, is a single line which links to their documentation site.
How do you Make Sure it Works?
Software is buggy. Projects go inactive. Their dependencies change. Their maintainers get disappeared over the Atlantic. So, how can a user assert – before going through the trouble of installing your project and trying it out – that it works at all?
You can use badges from services like Travis, Drone, and Coveralls to demonstrate your code worked somewhere other than your computer, but people will want to try it themselves, whether because they run an uncommon system or because they just want to see it for themselves. So, provide testing instructions.
If you ship your project without tests, shame on you. Look at your life. Look at your choices. Once you’ve come back and written tests, provide instructions on how to run them. For most of my projects, it’s something like this:
To run tests, get the source code and use setup.py:
git clone firstname.lastname@example.org:"DATABASE API CALL"/porc.git cd porc python setup.py test
That snippet comes from Porc. If your tests need you to set particular variables (ex: an API key) indicate which, and how.
How can folks get involved?
If folks have problems, ideas, or just want to lend a hand, where should they go?
- Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug. There is a Contributor Friendly tag for issues that should be ideal for people who are not very familiar with the codebase yet.
- If you feel uncomfortable or uncertain about an issue or your changes, feel free to email @sigmavirus24 and he will happily help you via email, Skype, remote pairing or whatever you are comfortable with.
- Fork the repository on GitHub to start making your changes to the master branch (or branch off of it).
- Write a test which shows that the bug was fixed or that the feature works as expected.
- Send a pull request and bug the maintainer until it gets merged and published. :) Make sure to add yourself to AUTHORS.
Although Requests is an open-source project, these principles are just as important for teams on closed-source projects. A strong contributors section will reduce onboarding time from months to minutes, and reduce how much bandwidth onboarding takes from your existing team.
What’s the Project’s License?
Lastly, answer the question, under what circumstances can I use this project? This can be as simple as a link to opensource.org‘s page on whichever license your project uses. You could also link to your LICENSE file, which should have the text of your license.
Why is licensing important, even for open source? Because by default, you, the author, own the project. Anyone using it is violating your property. Even if you’d never take anyone to court over that sort of thing, how can a visitor be sure? State your license! Know your rights!
Your readme is your project’s first impression. Make it great, and your users (and your future self who forgets how this dang project works) will thank you.