DEV Community

Nerando Johnson
Nerando Johnson

Posted on • Edited on

5

Writing The Needed ReadMe

A Guide to the Importance of Writing Good ReadMe’s

Black female developer

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.

Project title

A little info about your project and/ or overview that explains what the project is about.

Motivation

A short description of the motivation behind the creation and maintenance of the project. This should explain why the project exists.

Build status

Build status of continus integration i.e. travis, appveyor etc. https://getbootstrap.com/b. Ex. - Build Status Windows Build Status

Code style

If you're using any code style like xo, standard etc. That will help others while contributing to your project. Ex. - js-standard-style

Screenshots

Include logo/demo screenshot etc.

Tech/framework used

Ex. - Built with

Features

What makes your project stand out?

Code Example

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.

Installation

Provide step by step series of examples and explanations about how to get a development env running.

API Reference

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.

Tests

Describe and show how to run the tests with code examples.

How to use?

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.

Contribute

Let people know how they can contribute into your project. A contributing guideline will be a big plus.

Credits

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].

Anything else that seems useful

License

A short snippet describing the license (MIT, Apache etc) MIT © Yourname

view raw README.md hosted with ❤ by GitHub

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)

Collapse
 
jasonbbelcher profile image
Jason Belcher

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.

Sentry image

See why 4M developers consider Sentry, “not bad.”

Fixing code doesn’t have to be the worst part of your day. Learn how Sentry can help.

Learn more