Write a better README.me

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 at 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 in 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 are 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 leads 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 at 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.