Write a better README.md in four easy steps

Photo by Scott Graham on Unsplash

Most projects have a README.md file, but many fail to deliver anything more than words.

Don’t pack a book about your project on a single markdown file. Break it if necessary!
If a given topic gets too complicated or verbose, break it.
Don’t punch your visitors with that 30 step update guide on first sight!

Don’t saturate your README with external links. Links break. Webpages move and content change.
You may end up pointing to the wrong direction.
And let’s be honest: no one likes to update documentation because a blog post changed.

It sucks to open a project and be granted with something like:

The project depends on external-package, to install it, run:
sudo apt get install external_package
# arch
sudo pacman -S ext_package
# fedora
sudo dfn install external_package_2
# macos
brew install epackage

Don’t teach people how to use a package manager, unless your project is a package manager.

If you do this, your telling your future self “Update the docs all the time”.
Instead, just say:

- external-package

At max, point to the project repository. The README is about your project, not about your project’s dependencies.

The will to prevent a lack of information oftentimes lead to an excessive focus on explanation.
Avoid explanation in general, keep the text about what’s your project, teach to install it and give a glance on how to use it.
Imagine you’re writing a description for a mailing library: instead of “We were facing a bug with our cache system in 2018, so we added the option to use multiple client configurations” (which is nothing but an explanation), tell “the project supports multiple cache client configurations”.
People want to know about your project. Your struggle should live somewhere else.

There’s no such thing as a ‘perfect project description’, but following those rules will help you keep sane, have more time to focus on the project itself and lead people through your guidance with a smoother experience.

Agree? Disagree? Tell me on the comments below.



Web developer. You can find me at: ulissescaon@gmail.com

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store