While a software project is growing, so does the documentation. There are large quantities of information that need to be transferred to many different people.

  • Users want to know how to use the software.
  • 3rd party developers want to know how to use your API.
  • Management wants to know all the business requirements.
  • Designers want to document why and how they do things. Same goes for QA.

But we are going to focus on a different type of documentation. Code documentation.

Code documentation, unsurprisingly, is documentation that accompanies the code of a project. It's written by developers for developers. It might cover just the high-level architecture or it might drill deep down into every single class and function.

When a new developer joins a team, they're usually presented with a few architecture charts and at best an outdated wiki that consists of a few pages. If someone on the team is great at explaining things, the newcomer is in luck. But if not, the process of comprehending and internalizing a whole project can be a daunting task.

This is where code documentation steps in. If it is written well, there is no need for meetings at the white board about the data flow of the application. There's no need to explain the design patterns used.

But lets be honest here. As developers, we know that no one wants to write these docs. So much code to be written, not enough time. We'll dive into this soon, in part 2!

Arthur 👋