Writing Kickass READMEs

Pranit Bauva
Mar 14, 2017 · 7 min read

Writing documentation for code is extremely important. Alas! I realized this late. Nevertheless, you should not make this mistake again.

This is written with respect to software related READMEs, if you want guidelines for other stuff, then probably this isn’t the right place.

Let’s discuss the potential problems of not having a good README:

Not a clear description of the project

In fact some professional projects too have vague description and you are left clueless as to what the code does. Sometimes the project is so big that they can’t really mention all of it in one thing. That is the time you should probably split it in many repositories or folders (if you desperately want a big mono repo like Google) and each folder should contain some high-level information of what the code inside it will do, just like recursive Makefiles.

Not having a installation guide (or an incomplete one)

What a developer should understand is that since your development environment is setup to run that code, doesn’t mean everybody’s is. One should always write the whole installation process for all systems that the software supports and it should clearly mention that the software doesn’t really have support for this system but it would be great to support it in future or something.

For unix-based systems, one should list out all the ways to install the software. Let’s take an example of Ubuntu. If you have managed to get your software packaged with a .deb file and also uploaded it upstream so that it can be used with apt-get, then that’s just awesome!

Sometimes you might be releasing it and then packing the source code in a tar.gz format, still awesome. In the latter case, it would be worth while to mention all of the dependencies required. Also, just the name isn’t enough, their exact version numbers is even better because you might never know when a python code breaks because of the version bump because well that’s how things work in python world.

If you are expecting the user to do a gcc based compiling for each source code file then God just forgive you. It is time to move on to at least Makefiles to automate that process for you.

If something doesn’t work in particular systems, it is important to list it out.

No User Documentation

Also you can include the very basic use case in the README itself.

No guide for people to actually contribute

A very important part of the contributing guide is to setup the development environment. Again in this, it is worthwhile to get into the platform specific information. For eg. Windows will have different development environment while Ubuntu will have a different one. You should mention what IDE you used or the tools that you used.

Now your project might have some development related dependencies. You should mention about that too. Now finally the viewer can have successful environment setup to actually contribute to your code.

Now, you might be following some conventions for writing your code, right? It is worth while to mention the conventions that you have followed in a separate file and link it in the README.

Then you would have a specific way or two in which you accept others’ code, right? You might be using Github’s Pull Request based system or the age old sending patches via email using git-format-patch and git-send-email just like old times. Whichever you prefer, it is important to specify this in a new file possibly named as CONTRIBUTING GUIDELINES or something. If you have any specifics about the project mention it there. Don’t just expect people to know it by default.

It is also worth while to link the easy to fix bugs for new comers so that they can get familiar with the code base without trying to mingle with the core parts of the software.

No technical documentation

No mention of how to run tests

No license

No place to mention about bugs

No mention about the version control system

No contacts

No fancy GUI pictures

No table of contents

Okay, now that I have ranted a lot, I hope you know How to Write KickAss READMEs.

This article originally appeared in Pranit Bauva’s website.

Kharagpur Open Source Society

We are a group of Open Source Enthusiasts who focus on something more preliminary and relevant, "A Love for Coding".

Thanks to Ayush Goyal.

Pranit Bauva

Written by

Sportsman turned into programmer and mathematician

Kharagpur Open Source Society

We are a group of Open Source Enthusiasts who focus on something more preliminary and relevant, "A Love for Coding".