July 29, 2015Kenny Durand4 min read
At Theodo, we are used to working on different kinds of projects. We work on massive projects, with many developers and a long time of development involved. We work on very complex projects, with specific technologies or infrastructures, that we're not always familiar with. We also work on pretty simple and straight-forward projects, but with a lot of existing code.
These situations lead us to some kind of "information volatility hazard": there is a risk that information gets lost from a developer to another, gets forgotten between the beginning and the end of the project, or simply that you don't manage to solve a problem in an easy way, just because you can't see the problem has already been handled before.
After working on various projects, I became sensitive to the way information gets transmitted among the team, and (even more important) how it is described. The worst thing that can happen in a project is when a developer takes some time to write documentation, and the rest of the team can't find the crucial information.
As a result, I began building a README template, that could help us structure our knowledge on projects in a unified and accurate way, for any kind of technology we are working on. The aim was to have a simple, yet exhaustive list of what we need to know in our daily developer lives. We've been using it for a while on many projects. After some field testing and improvements, it's now time to share it with the world! :)
As I told you before, the "frontpage" (I mean the README.md) of this documentation contains only the name of the description of the repository, plus a list of sections... Oh, and we also included the name of the people who contributed to the project. And this is actually a really important part you should not forget! Believe it or not, human beings are the best source of information (true story). That's why you should always keep in mind (and in your README) who worked on each project, in case you need a hand to solve a tenacious bug. Regarding Theodo projects, we split the team according to the role of each person, so we added our Scrum Master and our sales person for each project.
Then, let's talk about the different divisions in our documentation. Each time I struggled on a project, I tried to understand what was blocking me; I ended up categorizing the problems into six sections:
Obviously, this structure is completely flexible: feel free to add any relevant section (or remove any irrelevant one), based on your project, its technologies, and more important: its team!
I hope this README template will help you organize and clarify information in all your projects! Please contribute to the README template repository through pull requests or issues.
And remember: a good documentation should stay simple and go straight to the point. Don't flood your README with thousand of sections, or your coworkers won't read any of them! As Saint-Exupéry said:
Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.
Web Developer at Theodo