Writing a readme on GitHub is no rocket science. You're probably after the two most important steps in reverse order of difficulty: creating the project, and naming it. Here's how you can create an awesome readme to your project.
When I studied journalism almost a decade ago, I was taught to answer these 4 questions (+2 optionally) when writing an article:
- What?
- Who?
- When?
- Where?
Writing an awesome GitHub readme is no different to this. When someone finds out about your project, and wants to find out if it'll be helpful for them, you can help them by answering these questions.
What?
This is pretty simple. Just state what your project is about. The easiest formula to follow here is to put it in a simple sentence what your project does.
Pro tip: Include a demo video or some sort of visualization. Words can describe what your project does, a video or a gif can present it for instant understanding.
Who?
The second most important question you have to settle is who the project is for. It's important to signal any dependencies or technical constraints right from the get go. It can be any language or OS specific constraint, but you have to be upfront about it, so the user doesn't waste time on researching something they simply can't use to solve a problem.
When?
A well written use case describes a situation when a user can benefit from your project. You clearly understand the problem the project solves, so you can just simply write down a scenario when you were frustrated and your solution would've been useful.
Pro tip: Sometimes your users find new use cases, so feel free to add new items to this part on the fly when you find out about it. You never know how commonly the use cases your users figure out emerge in real life.
Where?
This is pretty simple: include where your users can get started. This might be an npm or a docker command, or a link to somewhere. In case a user needs to do some type of configuration, it's good to have some form of description about the necessary steps to spark up your project.
Here's an Example
Check out dyrector.io's readme and see how we did with this formula.
We wanted a readme that describes how the project is useful by answering the questions:
- What? ✅
- Who? ✅
- When? ✅
- Where? ✅
And additionally, we added one of the two optional ones (how & why), as well:
- How? Described how the solution works by describing dyrector.io's stack and including a diagram.
Give us a ⭐ on GitHub
Did you like this blog post? Well, I have no platform where you can support me, but...
Can you take a second and star dyrector.io's repository on GitHub at the link below?
It would make my day! Cheers!
Top comments (0)