13
How to write a good README
A README is a great way to show people what your project can do, and why it matters, and here I'll show you how to write a good README.
Check out my community-health repo, and follow the instructions in its README to quickly get started.
So, you in for the read? Great! Let's start 😄
Your README should be a concise gateway to all other resources. It should answer these questions as fast as possible:
- What is the project for? (A short description)
- Can I use it? (Prerequisites)
- If yes, how do I install it? (Installation, Usage examples, etc.)
- How can I help? (License, Contributing, etc.)
Taken from here
Here are some general writing guidelines:
-
Keep your writing readable as a raw file.
Sometimes, people may read your project as an unrendered, plain markdown file. It may be for editing it, or just because they have a local copy of your code. Make sure your README is still readable for them.A few tips to help make your Markdown readable even if it is raw:
- **Always break lines!** Set your editor to show a ruler at ~80 characters. This is done so that people who are reading this as a raw file don't have to scroll infinitely.
This is not a hard and fast rule though. Also, you don't have to break a line for that one last word which overflows (except if it is "Pneumonoultramicroscopicsilicovolcanoconiosis" or something 🤣).
- **Minimise HTML.** Keep your markdown file as much markdown-y as possible – you don't want people reading HTML! Only use HTML if it is really helpful to the readability of the rendered content. A good example of when to use an HTML tag is the `<details>` tag.
- **Use reference-style links** because you don't want a super long link to break the flow.Keep a light, friendly tone. Write as if the reader doesn't know too much but is really interested
Keep it brief
Link to other places in the files only for additional information.
When linking, inline the relevant information.Use as many images, snippets, commands as you can. Show them, not tell them.
Check out this markdown style guide or this style guide and other available markdown style guides.
Obviously, the first thing that should appear on the README. Consider linking it to the project's GitHub repo.
Badges are a great way to show tiny tidbits of info. They also attract the eye but don't overuse them.
You can also make these badges link to relevant pages. For example, the stars badge could link to the stargazers page.
Banner images are better, but you can choose any. Look at this beautiful example of a banner by atom(Coincidentally, I based most of my studies on atom's repos). And this is a nice example of how to place a logo.
You can also add some additional images under your banner.
Make your project description short and to the point. This is a template you can use, borrowed from scottydocs' README template: <project_name> is a <utility/tool/feature> that allows <insert_target_audience> to do <action/task_it_does>.
You can also add another line or two, but don't go overboard.
Add a quick list of highlights. Here's an example:
- Fast. See [benchmarks](#benchmarks) for more info
- Small. Only `1kb`
- etc.The next thing to do is list out the prerequisites. Make sure all these are included (in order of importance):
- Which OSes (OSs? OS's?) are supported
- What dependencies and tools are needed
- What knowledge is required
Show installation commands. Even though programmers have magical capabilities, copy-paste is preferred (by most people).
Also, if there is a CDN, show an example of how to use it.
If you have nightly/beta versions, show how to install them too.
Show as many usage examples as possible. Show the simplest, quickest way to use the project. There is rarely a code snippet that works all the time, so make sure to provide multiple examples if there isn't.
Bonus points if you link to the documentation!
For the "how to contribute" section, just quickly show how to fork, clone, and set up the repo, and link to a contributing file for details.
For crediting contributors, you could do it manually, or you could use something like All Contributors
If people have made it all the way here, they are definitely interested in the project as a contributor (If they weren't, they should have left after the usage sample). So, mention which license is used.
Now you know how to make a good README! Thanks for reading! 👋
(Fun fact: I used <esc> :wq to publish this post 🤣🤣)
13