Sep 17, 2020
Write a better README.md in four easy steps
Most projects have a README.md file, but many fail to deliver anything more than words.
Tip #1 Keep it tidy
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!
Tip #2 Trust no one
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.
Tip #3 Maintain the focus
It sucks to open a project and be granted with something like:
The project depends on external-package, to install it, run:
#ubuntu
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:
Dependencies:
- external-package
At max, point to the project repository. The README is about your project, not about your project’s dependencies.
Tip #4 Don’t explain too much
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.
