Introduction

This week I was working in my talk that is going to be presented to university students, this week I review the topic about documentation on the book software engineering at Google, also I assisted to the first Pioneras Conf in my city Medellin, this Conf was targeted to girls that want to start their careers in tech, there was a great attendance and come people from everywhere, PionerasDev is an NGO in my city that aims to include more women in tech and help growing their careers, definitely check on that it’s an impressive initiative. Maybe in future entries I include some of the topics that I learned at the Conf.

This week I’m going to talk about documentation. How to manage? How to write? Why is it important? What type of public read documentation? What type of policies do you need to include to manage documentation? So let’s get started.

Documentation

Documentation is a serious topic that nobody wants to speak about, most of the engineers hate to do this task the have many reasons for this like: the extra effort in writing about the code, engineers tend to think that they are not capable of writing good documentation or think that writing as a different skill to acquire. But we should insist on increasing the amount of documentation and the way to accomplish that is to take documentation seriously.

The way to make documentation serious is to treat it like code, this means to create tasks related to documentation, making pair reviews, create a version history and prioritize on your sprints. It sounds like a lot of work but this is an investment that will pay over time, there are many benefits when you write it: helps you to remember what the code was about in the first place, reduce questions when someone else read it, force you to think if the code makes sense and signals that is a professional codebase and well maintained. Once the culture of writing documentation is established more people will get into it. So the next question is: how do we write good docs?

How to write documentation

When writing you should always ask yourself: for who I am writing for? The number one mistake when we are writing is to think from our perspective and doing so makes the text biased towards our own perspective, we consider that everyone shares our context but they do not. For this reason it is always recommended to make a pair review (like code) so you guarantee that other people are also able to understand what you write.

“Optimize for the reader”
Software Engineering at Google

If you do not know where to start is a good idea to make these questions in order to get understanding the context of your topic:

• Why were these design decisions made?
• Why did we implement this code in this manner?
• Why did I implement this code in this manner? And imagine you’re looking to your code two years later

So when writing the documentation on your code, focus on the questions: what does this code do? And why was it implemented in that way? Those are the common questions a future reader will have when reading the code. But if you want to go deeper you can ask yourself more questions to get more information.

There are common questions that help you to include all the possible information around a topic, I am referring to the 5 w’s and h, these questions are: what? why? when? Who? where? And how? Asking this questions helps you to gather information on any topic, for example you can ask yourself the following questions:

• What is this doc for?
• When was created?
• Who is going to read this?
• Where does the doc be saved?
• Why does this document exist?

With those questions answered you are able to check if your documentation is precise and have all of the information needed to make it. But until this moment we didn’t ask ourselves about what kind of readers exist. So let's see what kind of readers we can encounter using our documentation.

Types of audience

There are different types of audience depending on the level of engagement in the project. We can classify people in 3 types and we’re going to imagine who is these people if you were creating a library:

• People working on the code: these people are programmers related to the project and are experts in the programming language. In your library they would be the maintainers of the library.
• Consumers: people related with the functions that the code or the API provides and only consume what is there. They are the people who download your library and use it in their code.
• Specific task: people that are looking for how to accomplish a task. They are the people that don't want to go deep in your library but need it to do some specific task.

Keeping in mind for who you writing for helps you to focus what are the topics you need to write about, because consumers of a library doesn’t want to know the specifics about how you implement a thing, but for a maintainer want to go deep in the specifics because maybe that helps them to fix something in the future, meanwhile for the people who wants to do something specific just need to find how to do their task. And you need not only to consider the level of engagement also the way they are searching information.

The searchers navigating your content could be classified by two types:

• Seekers: this is the kind of people who know what they want. To help them to get what they want quickly, give them a good structure easy to scan through the document
• Stumblers: they don’t know what they want. To help them, give it a summary at the start or the end of the document to know what the document is about

Giving a good structure and summarizing your docs help to different kinds of people to be guided through the document. But you think that only comments on your code are the only documentation needed? There are many types of documents that you are able to include in your projects.

Types of documentation

There is more documentation than just commenting your code and we are going to explore what other kinds of other documents you could include inside your project. We could say that there are these types of documentation: code comments, design docs, tutorials, conceptual documentation and landing pages. Let’s see each one of them.

Code comments

This is what pops out of our mind when we think about documentation, this is the most fundamental way to document and it is a good idea to include these activities into our workflow to improve maintainability over time. A lot of programming languages had their own syntax to create documentation that facilitates this job. For example JavaScript has JSDocs and Python has PyDoc to document. Getting to know how it works those standards is beneficial to you and your team to use it and read it properly.

And what to include in our code documentation? The question is a little bit uncomfortable, you can consider asking yourself the following questions to write about: what does this code do? What was the reason to create this function, class or whatever? What is the expected result? What is the main use case or use cases to use this? What does this module include? What are the edge cases? Depending on the type you are describing it is nice to have some things, for example classes it is beneficial to write about the purpose of the class and important methods of the class. Functions should start with a verb because they do something and is a good place to describe parameters, return value and exceptional cases. To see it let’s take a look at an example.

Let’s take as an example this piece of code:

## Maybe include an example of code
class Vehicle: 
  def __init__(self, color, wheels, seats):
    self.color = color
    self.wheels = wheels
    self.seats = seats
    self.speed = 0
    self.is_on = False

  def accelerate(self):
    self.speed += 1

  def brake(self):
    self.speed -= 1

  def start(self):
    self.is_on = True

  def stop(self):
    self.is_on = False

  def paint(self, newColor):
    self.color = newColor

  def __str__(self):
    return f"""{self.color} vehicle with 
               {self.wheels} wheels and 
               {self.seats} seats""""

It’s clear enough but let see how becomes more easy to read with some documentation and put on the perspective of someone that use this module or doesn’t want to know the specifics of your code and the people that will read this code in the future:

class Vehicle:
  """
  Represents a vehicle into the game, the user is able to
  personalize color, wheels and seats. When the user drives 
  is able to change speed and turn on or off the car whenever 
  they want to. 

  In order to change speed of the car you need to `acelerate()` or 
  `brake()` to increment or reduce speed.

  To be able to use the car you are able to use `start()` and when 
  you are done use `turnOff()`. 

  To change color use `paint()` to assign new color. 
  """
  def __init__(self, color, wheels, seats):
    """
    Initializes the vehicle with the given color, wheels and seats.

    color: string - RGB color of the vehicle
    wheels: number - number of wheels of the vehicle 
    seats: number - number of seats of the vehicle
    """
    self.color = color
    self.wheels = wheels
    self.seats = seats
    self.speed = 0
    self.is_on = False

  def accelerate(self):
    """
    Increments the speed of the vehicle by 1.
    """
    self.speed += 1

  def brake(self):
    """
    Reduces the speed of the vehicle by 1.
    """
    self.speed -= 1

  def start(self):
    """
    Turns on the vehicle.
    """
    self.is_on = True

  def turnOff(self):
    """
    Turns off the vehicle.
    """""
    self.is_on = False
    self.is_on = False

  def paint(self, newColor):
    """
    Changes the color of the vehicle to the newColor.

    color: string - RGB color of the vehicle
    """
    self.color = newColor

  def __str__(self):
    """
    Return a text with the description of the vehicle

    Returns: string - a string representation of the vehicle
    """
    return f"""{self.color} vehicle with 
               {self.wheels} wheels and 
               {self.seats} seats"""

If you are not familiar with Python docstrings you can read more here. At the start we include the use case for this piece of code and describe what actions to perform at the definition of the class. In each method we describe what is the action expected, a key here is to describe what is this method doing but don’t explain how, the how is the code. And for functions with a return funciton like the last function we describe what is the return type expected. These comments will help you and others in the future to better understanding.

When you include this as a common practice this increases usability because you indicate what this module does and when someone else is using this, the code editor will tell you what is the goal of each thing. The end result is a larger file but overall it is a great improvement. If you see the first code was not bad but with the documentation it shines and will improve collaboration with the rest of the team.

Design docs

These documents are a good way to create a register about the design decisions and discuss with other engineers, you can think about the design docs like the planes of the building, they describe what we’re going to do without making all the effort on creating the thing. In these texts you are going to talk about the goals of a new project and implementation details, strategies, pros and cons of each strategy and anything you need to take into account. These types of documents are required to start a new project at Google, imagine the importance of these.

So you can consider doing this type of document when you want to start a new project or doing a great effort and you need to think deeply on how to do it. To facilitate things I am going to include a template of the design doc made by @charlieBot a former engineer at Google, that you can check at the design doc template here. Using the template will make easier to start using it.

Conceptual documentation

Sometimes you need to introduce new ideas that are not trivial when someone reads your code. A conceptual documentation could be the key to guide new people to get familiar with new terminology that they don’t know. In this type of documentation you can explain what that concept is about? How to use it? Why was the origin of that? Why is it necessary? And maybe how to facilitate things when using it? This documentation is useful when comments in code are not enough to elaborate certain ideas that go beyond you possible write in a comment.

Tutorials

How-to guides are valuable, the most important guide that you need in your project is how to set up and get started in your project, this way new people are able to start to contribute to your project quickly, this kind of guides are straightforward to write because you need to describe step-by-step what the user should follow.

When write tutorials is good to follow this tips:

• Add numbers to each step
• Add a new step when user input is required
• Clarify if a pre-condition is needed to meet in order to do some step correctly
• Give a clear indication of what the user needs to perform at each step
• Show what is the expected output
• When done with tutorial, try it to verify that the steps execute correctly

Following these guidelines will make it easier to write clear tutorials to end users.

Landing page

A landing page is perfect to organize your information and add navigation to what you document in your project. You need to make this right because maybe it is the first contact with the project for so many people so having a good structure facilitates users to navigate through the information easily. So check that it is easy to navigate through the documentation.

But every documentation comes to an end, let’s see how to deprecate a documentation.

Deprecation of a document

Like software, documentation also has its own life cycle and when documentation is no longer useful you need a way to indicate the end of their life by adding some comment at the top that says: “this not longer works!” and redirect to recent documentation if appropriate. But please don’t let deprecated documentation go freely without people knowing that it is not useful any more.

Useful policies for documentation

The best way to maintain good documentation is to treat documentation like code. So there are some policies that will help you to increase ownership on documentation on your team:

• Documentation needs to have version control: in order to have a good control on what you did and to recover something when you need to.
• Clear ownership: assign a responsible to maintain a doc. when people are able to give feedback to someone is easy that get fixed when there is a responsible to do it
• Do pair review: when a new change is going to be published it is necessary that someone else review the new changes.
• Have issues tracked: like a code when a bug appears is registered in your task manager, when something needs to be improved on documentation put it on your task manager and do a follow-up.
• Periodically evaluate: time to time review that the documentation is accurate with the information, this is critical for something like set-up tutorial

The main idea is to leverage from the established process to use it with your documentation so it is easy to maintain the workflow and not do an extra process just for documentation.

Final thoughts

I was impressed by one idea of the book that states something like the state of documentation in 2010 was the same as testing in the 1980's, this means poor tooling and almost no worries about this topic. With the implementation of policies mentioned before there was a good improvement at Google but still there is a good improvement margin in this area. For example some new tools are appearing like Storybook for UI components is something fresh that is going to become a standard in all JavaScript projects but I could imagine this is going to happen in other types of similar projects in other languages.

So investing time in integrating better tooling to document is going to make things easier and things like LLM (Large Language Models) like GitHub Copilot will make this tedious task more easy to the developers bringing to them a better experience in the future.