Start with documentation

I’ve started a new simple approach over the past years, and I’d like to share it with you.

Permalink to heading Don’t hurry Don’t hurry

One of the biggest mistakes you can make is to hurry without good reason.

I mean, sometimes you have to turn yourself into a speedster because of very short deadlines, but that does not mean you cannot take some time to think before coding.

Many bugs and oversights will never occur if you take the time to review your code, write tests and consider even the most absurd usages.

We are humans, and sometimes we make mistakes. However, there are ways to fight against that natural inclination.

Permalink to heading Document your code Document your code

Documentation is the link between humans and code. It’s not only useful for your customers, your teammates, your future teammates, but also your “future self”.

What I mean by “future self” is you, as developers, weeks or months later.

Whether it’s a simple README file at the root of your project, a GitHub wiki, or a complete website, the documentation is precious.

It provides useful help and links for everybody, including contributors, developers, marketing and sales teams, and customers.

You can also include pure technical sections such as API documentation for developers.

Those sections are great places to explain your technical approach. It forces you to think about usages, edge cases, maintenance, and purpose.

It does not have to be public all the time, you can write private documentation too, for example, in private repositories.

Permalink to heading Meh, the code should be self-explanatory Meh, the code should be self-explanatory

I’ve met some developers that are reluctant to write documentation. Most of the time, they consider it as useless extra work.

No need for unnecessary comments, as nobody likes comments like that:

// process form
function processForm()

While I understand why it’s useless in this example, I think there’s a misunderstanding. Nobody wants poor documentation.

Good documentation brings value. You don’t have to explain every single function or class you make. Instead, you give useful hints for usages, maintenance, and evolution, and it’s an excellent document you and your teammates can use to discuss.

Permalink to heading Wrap up Wrap up

Good documentation is not optional. Every time I start using a new tool, I read the documentation. Why not write the documentation before coding.

So far, the coding phase has been significantly faster, so it’s not a waste of time at all. It makes both the code and the documentation more robust.