Creating a Better ReadMe for GoLang Packages

We’re lucky in the Go community in that we decided to converge around simple but very useful tools early on in the ecosystem. go fmt is always looked at as one of the most important tools for your average Go programmer. Many other tools have also risen to prominence and become really, really useful. We have it good - though perhaps you make your own luck.

However some things can be better.

For example, better ReadMe files on our project pages.

One of the tools in our arsenal is godoc which is pretty wonderful, even if it is simple. It does most of what we need and provides enough to make us happy. Almost everyone knows to add comments to our packages for godoc to process and display.

This is not so for ReadMe files. Many have essential information missing, links to GoDoc missing, and worst, no example code showing how to use the package.

But let’s step back and figure out firstly who the ReadMe files are actually for.

Whilst GoDoc is aimed at the library user, the ReadMe files in our repos are designed for two types of people:

1. potential users
2. potential contributors

It’s the first of these I’d like to address here.

Even though godoc has all of the information about what a library does, many times there aren’t enough examples to actually show how to use it. Some libraries are difficult enough that trawling through godoc doesn’t help you get to the point of using it. This is especially so for people new to the language - it can be fairly opaque.

And of course, if you are searching for potential libraries to use, you quite often end up at the repository’s project page and not it’s GoDoc page (most search engines link to the repo, not the godoc page).

It is here that we need to show the user how to use the library!

We also need to show the user that we have taken care when creating all of our line-by-line written code, by producing documentation that lives up to our craft.

There are a few things the ReadMe needs, but the most important in my opinion is an example showing the user how to use the library. You also need to show what the result is too! If you miss this part out, you’re not helping the user decide if they want to use your package or not.

There are a few things the ReadMe also needs, such as:

1. a link to the godoc
2. a license

But there are also many things the ReadMe could have:

1. a badge to your testing (CI) status
2. other badges for code linting/vetting/report
3. author information
4. how to contribute
5. contributors

Announcing GoReadme

And with that, and not forgetting all the other things you need, I present a small app called go-readme which helps you craft a ReadMe which contains most of the important details, examples, and links you need to create beautiful ReadMe files.