A Guide to the Importance of Writing Good ReadMe’s
So here you are, you have good written code and uploaded it to whatever open source repository you use Github, Gitlab, Bitbucket or even your own hosted repository. You are sure your code works, you have tested it, retested... even tested it on Becky's machine and refactored it on your machine and sure it works. So the question to the person who looks at you repo is ...... HOW THE HELL DOES IT WORK ?????
Why care about the README ?
As developers, we release tonnes of projects on open-source repositories. A good ReadMe allows you and your project the ability to standout among the sea of developers, it should be well crafted as your project. In brief, a ReadMe is like the face of your code. It is the first file a new user should read when encountering your project repo , and it should be written as a very brief and giving very basic introduction to your code. In other words ‘ A good README is for others to understand what our code includes, and why it's noteworthy. A README file is also essential to retrieve a project - on GitHub but also in browsers.
Another insight for Junior Devs
OK, now let's check why we should care for our README files since the first project! Even if the code is just for you, possibly you will come back to it after a while. A good README enables you to relaunch a project - without wasting your time on recalling: What was it all about?
For a budding programmer, GitHub is a calling card. The pinned projects on GitHub are most often in our portfolio or are our portfolio. When we're at a career stage without a considerable commercial experience or nice-looking non-profit projects, a presentation of our achievements in a form of repositories is one of the best way to get visible to the recruiters and potential employers.
A preparation of several demonstration projects we want to show off during the interview works the best. If we are just learning and we drop our training projects there, let's pay attention to their good description. Even a non-technical recruiter will be able to recognize the technologies we touched, and check if it goes in line with a candidate's profile he's/she's looking for.
Lets take A Closer Look
So lets examine how a good ReadMe makes all the difference in if you would use an open-source project. Look at this repo's ReadMe, how does it work, what does it look like…… nada, zilch, no details. Thus, therefore I am way less likely to use this repo or even learn from it.
This repo’s ReadMe on the other hand give the perspective user a better idea of how the code works, what is it all about and how they can use it .
Ok enough talk, how do we do this….
Below is an example of a good layout for a ReadMe citing the various sections and what they should contain.
A little info about your project and/ or overview that explains what the project is about.
A short description of the motivation behind the creation and maintenance of the project. This should explain why the project exists.
Build status of continus integration i.e. travis, appveyor etc.
https://getbootstrap.com/b. Ex. -
If you're using any code style like xo, standard etc. That will help others while contributing to your project. Ex. -
Include logo/demo screenshot etc.
Ex. - Built with
What makes your project stand out?
Show what the library does as concisely as possible, developers should be able to figure out how your project solves their problem by looking at the code example. Make sure the API you are showing off is obvious, and that your code is short and concise.
Provide step by step series of examples and explanations about how to get a development env running.
Depending on the size of the project, if it is small and simple enough the reference docs can be added to the README. For medium size to larger projects it is important to at least provide a link to where the API reference docs live.
Describe and show how to run the tests with code examples.
If people like your project they’ll want to learn how they can use it. To do so include step by step guide to use your project.
Let people know how they can contribute into your project. A contributing guideline will be a big plus.
Give proper credits. This could be a link to any repo which inspired you to build this project, any blogposts or links to people who contributed in this project. For example, this was borrowed from [https://gist.github.com/akashnimare].
A short snippet describing the license (MIT, Apache etc) MIT © Yourname
But how does it look ?
Now that you have taught yourself how and what to write in a README, let’s talk a bit about the styling of README aka formatting.Formatting is an essential part of README. You can learn more about how to format your README from here and here.
In the end, Keep in mind —
You don’t need to go full-bore Readme Driven Development, you don’t need to include all those bullet points , you don’t need to follow any particular process. But writing a good README will definitely improve your documentation skills which will make you a better developer.
Other persons take on the matter :
@sindresorhus,@noffle and @matiassingers.
I really hope this helped to change your mind on your code is written, till next time. Feel free to send feel back in the comments below or follow me on Twitter @Nerajno.
Top comments (1)
Great info on how to write an good read-me that is sure to better your chances of someone using it first of all and second of all less frustration and murderous rage from some poor hapless developer somewhere that "attempted" to use your project unsuccessfully.