Documentation

Conversations around documentation in the context of software development aren't easy because developers have the tendency to equate documentation to documenting code. That has a bad reputation in the industry. There are so many quotes about good code not needing comments and as many jokes about comments being always out of date. These jokes and quotes make a fair argument in favour of writing better code - who wouldn't agree with that anyway? But they devalue documentation as a whole. It's easy to see people stretching these arguments to the point of saying that not writing any documentation is fine because the code is documentation.

Documentation says a lot about the culture of a company, and the so common absence of documentation says a lot about the culture of our whole industry. Once again, the problem is that we focus too much on the code. Working in a software development team comes with many responsibilities that aren't closely connected to the code:

• What recurrent meetings are you required to attend?
• How do you operate your own systems?
• What does that funny acronym mean?
• What are you supposed to do if something breaks?

Those are just a few examples, but you get the idea. Being a developer doesn't mean writing code all day long. It's called software development, not code typing. Being a developer means participating in the activity of building a system with code. A big chuck of these activities change at a completely different pace than the code itself. You deploy changes to your system multiple times per day (and if you don't, why not?), but it's highly unlikely that you change the way you operate your systems or your required meetings every day. From that perspective, half of the jokes we make about code comments becoming outdated at the speed of light don't apply. Also, the idea that code must be so simple that it's self-explanatory doesn't apply, because code can't explain funny acronyms. Code tells you how, but can't tell you why. Documentation is an expression of company culture because good documentation makes people comfortable and confident.

The way you document what you do, how you do it, and why you do it says how much you care. Most companies don't document any of it; they're fine with their culture being ambiguous. I strongly recommend to have a developer book: a small manual that documents the way you do things, how you do them, and why. In Developer book, I discuss how to structure, share, and evolve such a document. Here I want to focus on the aspects of the document that impact your culture: a developer book makes a big difference to the onboarding process. How much you care about new-joiners and how easy it is for them to get up and running is a defining aspect of every company. In most cases, it takes months to understand the vocabulary of a company or why some servers are called like stars and others like "Rick and Morty" characters. A few brief documents have a great impact on the way teams work together and clarify what things really matter to you. These documents help you foster a documentation culture which makes people better writers.

In order to mitigate the bad reputation documentation suffers from, I focus my personal writing efforts on explaining the whys of things. A common problem with documentation is that we just document what we do. But the actual power of documentation comes from explaining why we do things the way we do them. A good example is commit messages. They often describe the code change literally. That isn't helpful, because the version control system can do that. Knowing why changes everything, because it gives people context about the change itself. Bear in mind that commit messages are just an example. The point is, you have to make sure that documentation is valued by your teams. Leading by example goes a long way: write documents that explain why you are doing something, don't send a memo out that just says something is happening.