Readme First

What came first — the chicken or the egg? The project or the README.md?

As developers, we need documentation to work on a project. But at the same time, documentation needs developers working on the project to exist — otherwise, it’ll remain just another boilerplate template.

Here are three ways to improve how you document your projects:

1. Know your goal

Why are you writing documentation? Not just because “it’s required,” but what purpose will it serve?

Do you want to help others set up the project locally and deploy it to production? Explain what it does to a broader audience? Define working guidelines for contributors? Provide a usage guide?

Each of those is a good reason to document. Taken together — and clearly structured — they make your documentation much more valuable. With a clear purpose, it’s easier to organize your ideas and, more importantly, finish writing.

2. Take it seriously

Don’t leave it for the end. Treat documentation as part of development. As you build new features, update the docs accordingly.

If you postpone it, chances are it’ll become outdated — until eventually it’s so full of inaccuracies that it turns into dead weight. Once that happens, no one will touch it again. And few things are more frustrating than joining a project with abandoned documentation. It can drive even the most patient developer mad.

3. Practice

The only way to get better at anything is repetition — try, fail, adjust. Being bad at documenting isn’t a reason to avoid it; it’s a reason to do it more. You didn’t become a programmer by avoiding writing code.

Use every opportunity to polish your writing skills. If you make it a habit, it’ll become second nature.

A good Readme is worth a thousand Slack messages.

exit(0);