Your documentation is a direct reflection of your software, so hold it to the same standards.
After much practice, I have a recipe of sorts for writing READMEs that I follow anytime I make a new project. I wanted to share my process here, gather feedback, and see if I can lower the barrier to writing a good README.
This guide is geared towards projects that do not yet, or never will, have flushed out documentation. Once a project has a dedicated website, the README should turn into a minimal elevator pitch and "link fest" to relevant materials.
I think a "Highlights" section is one of the most important to include at the top of a good README. Create a simple, bulleted list of the main selling points of your software.
Here are the main takeaways of this guide:
- Make it inviting, friendly, and approachable
- Find the most appealing part of your software and sell it!
- Keep it concise; ain't nobody got time for your manifesto
- Have links to everything relevant (documentation, CI status, deployments, etc.)
- Emoji usage is encouraged (I'm only half kidding)
- A template for you to use!
If nothing else, try writing better READMEs because it will make you look more professional and legitimate.
A good README should include a brief overview section with a paragraph or two explaining what the software does, how it works, and who made it.
Feel free to include 2-3 subsections here with relevant information in regards to who you are and how the software is relevant in a broader ecosystem of software (perhaps respectfully compare your software to other solutions out there).
Consider the following:
- Your README is often the first and only thing anyone will see about your software.
- People judge your software by your README.
- Your README is shipped alongside your code within package managers.
In many people's minds, a poorly written README translates to poorly written software. Your README should convey the quality of your work, your expertise on the matter and get users excited by what you have done.
At the end of the day, your README is often the best marketing material you have.
Additionally, try to gear your README towards the average user. Assume some first-year Computer Science student is looking at your documentation wondering if coding is for them. Show them and the world what can be done with quality software and make them feel like your software is approachable.
When someone looks over your README, they should be able to find the answers to these questions quickly:
- Does this solve my problem?
- Can I use this code?
- Who made this?
- How can I learn more?
Try to streamline your README so that anyone glancing at it can answer those questions. This requires a bit of foresight into the typical kinds of problems people will come to your software for -- figure out those common problems and demonstrate a solution (even if that problem isn't the central aspect of your software).
On my point about emoji usage in the Highlights: besides being friendly and quirky, you can use emojis to break up otherwise plain text. In most of my READMEs, I like to use emojis in the section headers. This makes it much easier for me, and hopefully, others, to navigate the document.
To help people answer the question of "who made this?", include a subsection in your Overview to explain who created the software.
I'm Bane Sullivan and I created this guide hoping to refine my ability to create inspiring READMEs and help my colleagues better communicate what we are creating. This guide is my opinionated take on "how to write a good README?"
After all, we're in the business of Open Source Software for a reason: to share our work and make an impact. Having a well-written overview of our work is crucial in pursuing that goal.
Are you sold yet? Check out the included template to get started for your project!
Show off what your software looks like in action! Try to limit it to one-liners if possible and don't delve into API specifics.
This is where you need to give minimal examples on how to use your software to demonstrate what it can do. I often find that screenshots or animated GIFs are the most effective ways to communicate what your software can do, as most people just skim looking at the pictures.
When adding code, it is crucial to use proper formatting in code blocks with syntax highlighting:
import pyvista as pv
text = pv.Text3D('Write better\n READMEs!')
text.plot(cpos='xy')
It can be tempting to document your entire API in the README, and many projects have done a fantastic job of this like tqdm, but I'd like to mostly discourage this and gear you towards writing actual documentation and leaving the README as an elevator pitch.
You may be inclined to add development instructions here, but don't.
Having simple, understandable installation instructions is one of the most important things to get right in your README. Think about the audience you are going for and try to put yourself in their shoes: "what is a git clone?", "is a PyPI edible?", "who is this whale named Docker?", etc.
Most of the time, all you want to do here is show the one-liner to install your project using the relevant package manager:
pip install pyvistaI'm assuming that you are shipping your software off to some package manager; if so, you've made it clear that you intend to reach a wide range of users who likely aren't interested in contributing back to your software. With that in mind, save your development instructions (e.g., git clone ...; cmake ..) for the bottom of your README or another document altogether. The people looking for that know how to find it, whereas your average user will be scared off by complicated build instructions.
Additionally, you want to be sure to specify any minimum requirements to run the software here. If it is multiplatform, great, let people know that! If not, specify what platforms this runs on or which versions of Python, etc., are supported.
These are a few projects that I think have very effective READMEs. You look at the README and you can quickly gain what you need to answer the few questions I posed earlier.
There are countless others like these out there, but here are a few I strive to be like:
- fatiando/pooch
- Kitware/ITK
- gruns/furl
- marcomusy/vedo
- nschloe/meshio
- mher/flower
- giampaolo/psutil
- ahupp/python-magic
- curvenote/components
- MonitorControl/MonitorControl
I know you're all looking for an example of a bad README now, so check out py-filelock which only has a link to API docs -- no overview or anything 🤦♂️. I feel a little bad calling out a specific project, but you know what, I'm trying to make a point.
If you found this guide insightful or if you have suggestions, please start a Discussion!
When making open source software, you share your work with the world. Whether that is in the hope of contributions back, humbly if just one other person out there finds it useful, or building a community, I think it is important to solicit engagement. To do this, I like to point people over to the Discussions tab or invite them to request new features by opening an issue.
If you want to encourage others to contribute back to your project, this is the place to do it. Point people to your DEVELOPMENT and/or CONTRIBUTING guides if you have them. Further, you can outline any other ways to contribute such as translating the README or documentation.
