Tips to successfully build your open-source projects #3. Have a sexy README
The README of your project is crucial and strategic: this is the first thing people will see when they find your project. Whatever features you provide and however elegant your code is, most people will only look at your README. If your goal is to get traction on your project, the README is worth investing some time.
While it sounds easy to write a good README, I strongly believe most projects got it wrong, even really popular ones: some projects drown people with too much irrelevant information, while others barely describe what the project does.
It also took me a while to understand what makes a good README. The README template I use for my projects evolved a lot over time and it only got shorter to focus on what matters. I definitely have some room for improvement, but I think I’m heading in the right direction.
The overall structure of the README
A good README is a README that was written while wearing the shoes of the future reader.
Most of the READMEs are bad simply because they were not written with the correct perspective. Some project owners want to list every possible detail of their projects on the README, resulting in lengthy and hard-to-read READMEs. On the other hand, some other project owners believe the README is a waste of time and will put the bare minimum effort into writing it. In both cases, the reader was not taken into consideration.
That’s why it is important to understand what people are looking for when they are having a quick look at your project. To do so, a good start is to think about what you are personally looking for when you are searching for a library to use: What information matters to you? Do you recall some good and bad READMEs? What made them good or bad?
If someone is looking for a tool tackling his needs, I believe a typical flow could look like this:
- Am I in the right place?
- What does it look like?
- How do I get started?
- What is the license?
- Where can I learn more?
This is a list of questions your README needs to answer in a brief and clear manner. I am mostly going to use my library cpp_redis as an example to dive more into each of these questions, but don't take it as a single source of truth: there are many ways to design a good README.
The most important is to keep the README short and sexy while keeping it informative by answering the correct questions.
1. Am I in the right place?
When we first land on the Github page of your project, we want to understand what does your project do, in 2 or 3 lines.
We are not looking for a full list of all the features you support, but more a global description that tells us immediately what the project is about and whether it matches what we are looking for.
Yes, you have tons of features and tons of things to say about your project, but nobody really cares at that point. People will find more about your features in the documentation when they will need it: now, they simply want to understand if your library could be a good match for their needs.
In the end, think about this as an elevator pitch: learn to express the goal and value of your project succinctly.
2. What does it look like?
Once we have an overall idea of what your project is supposed to be and whether it might be relevant to us, we now want to see more.
In particular, we want to see what it looks like when your project is in action: What does a successful use of your project look like? What can I expect to achieve thanks to your project?
This part is trickier than it looks: the goal is to show the actual result, not the efforts to get there. Typically, we should show as little code as possible at that point (or even no code at all if that's possible!). In my opinion, an image (possibly a GIF) is better than words: just show, don’t explain.
For UI-related projects (websites, applications, UI libraries, …), this can be done by showing the UI. For example, look at these three Android libraries implementing a file picker:
- hedzr/android-file-chooser
For this library, the README contains multiple GIFs showing the UI/UX. It is very easy to understand what to expect from the library once integrated into your project.
- esafirm/android-image-picker
This library also has a GIF in its README. However, note that the GIF is hidden and that you need to click to toggle it. It's very easy to quickly scroll and miss out on the GIF. Additionally, the GIF appears to be compressed, preventing the project to shine at its best.
- coomar2841/android-multipicker-library
This library is a perfect example of what not to do: there are no visuals, so it is impossible to know what to expect. It is worth noting that the maintainer wrote some documentation, but the documentation also does not have any visuals. This means that we need to install the library and start using it before seeing what it looks like: that's a lot of effort and easily discouraging.
For projects without UI, it's much harder: what are you supposed to show if your project does not display anything? I haven't found a solution yet for my own projects. I think Ullaakut/cameradar is a good source of inspiration:
3. How do I get started?
From the two previous sections, we should have a good overview of what your project is about. If the project appears to meet our needs or piqued our curiosity, we now want to understand how to get started with your project: what are the pre-requisites and some basic examples.
The pre-requisites are a simple list of what is necessary to use your project. This can be other libraries, languages, compilers, tools, … Usually, specifying the versions is important. If you decide to support multiple versions of a dependency, make sure to set up some CI pipelines running your unit tests with each supported version, as suggested in my previous tip (Tips to successfully build your open-source projects #2. Test, test, and test again).
Having some examples in your README is important but be cautious: we only want a quick example that shows how to use the core features. You don’t want to show a long and complex example that takes minutes to go through and understand. Instead, you want to provide 20 lines of codes that show only the important stuff, possibly with some short comments. It should be easy to understand, and at the same time give a good idea about how this project can be used. Again, put detailed examples somewhere else and simply put a link to it.
4. What is the license?
Always make sure to license your work, even if you use a permissive license. Without the presence of a license, your work will be under exclusive copyright by default, meaning that nobody else can copy, distribute, or modify your work without being at risk.
The license will clarify your intentions. Without a license, others will not know whether they have the right to use your library, so they may just pass their way. If you do not have a license yet, and you do not know what license to chose, Github built a great tool to help you with that!
In your README, always name your license and put a link to it. Don’t copy-paste the full content of your license, that’s overwhelming and unnecessary.
5. Where can I learn more?
We have now put in the README all the most relevant information helping others to understand what the project is about, what it looks like in action, and how to get started.
If the project appears to be a good fit, people will now want to go further: learn more about the features in detail, understand more the limitations of the library, install the project, and get started with more complex use cases.
Add any useful and relevant links to go deeper into the use of your project. Documentation & Wiki is a must-have, but you can also include other links like contact information (email, Slack, IRC, …), or contributing guidelines.
The most important is to avoid putting the content directly in the README. The README is not a good place for detailed installation instructions and full documentation. There are much better ways to store and structure your documentation. Instead, your README is a very good directory to list useful links.
That’s all.
Any other information is usually irrelevant for most projects.
You may of course include some additional information like credits or author. But keep it short and at the very bottom of the README: people don’t care most of the time, except if it makes sense for your project.
Keep in mind that a good README is short and easily readable while containing all the essential information others are looking for. People want to understand quickly what your project does, not be drowned in details.
Don’t make the mistake to underestimate the README of your project: this is really the front page of your work and it deserves much more attention than people tend to think. And don’t forget to keep it updated as your project evolves!
Read all my tips to successfully build your open-source projects:
Originally published at https://cylix.github.io on September 9th, 2017.
