A great service needs a single source of truth

The importance of writing good software is generally recognized. So much so, that new tools and processes have been created to write cleaner code and make it easier to review and improve it.

Unfortunately, not so much emphasis has been put on the quality of the information that goes with the service a company offers.

A few decades ago, it was hard to retrieve some useful guidance. Then the internet descended upon us and suddenly it became easy. Notions hidden in some obscure manual became available on the internet in just a matter of few clicks. Unfortunately, things have changed for the worse.

It is so easy to put information online that many companies tend to overdo it.

The problem has shifted from not having enough information to having too much of it. Sorting the noise out can be an exhausting process. That’s why having a poor-quality documentation, dramatically lowers the chances that your service will be used by a large number of people.

As for code, less lines, less documents, less words have become more. Less documentation means it is easier for users to find what they really need, it is easier for them to get started with your service and get to know it better. Also, having a more concise material makes it easier for maintainers to “refactor” it and keep it up-to-date, improving the overall quality.

It is a much cleaner and enjoyable way to learn and dig deep in a service when there is a single source of truth, a single, reliable guide that tells users where to begin and where to end. A single place where to find a logical path to follow.

A couple of very good examples of a reliable source of truth are the Next.js and the React Documentation. To learn about all the Next.js or React features it is a quite pleasant process, as the information is well structured, concise and easily accessible for future reference.

The quality of the information you put online has a value. The more concise, the more valuable it is. This is why many authors make hundreds of thousands of dollars writing about things that are freely accessible on the internet. They organize the learning path under one single source, they save users time, they filter out the noise.

As someone said: “Perfection is achieved not when there is nothing left to add, but when there is nothing left to take away”. This is true now more than ever.

Sergio de Cristofaro is a full stack software developer specialized in Javascript, React, Redux, NextJS, Java, microservices and distributed architecture tools like Docker, Cassandra, Kafka and AWS.