Our starting point is as follows: code documentation is valuable, and a game changer for engineering teams.
To clarify this even further, code documentation – if it’s done right, if it’s kept up to date, and if we utilize different types of documentation for the purposes they best serve – profoundly transforms and changes companies.
Here’s how to make that happen.
Documentation types and purposes
Not all documentation is the same, nor should it be. The most common – low-level and high-level documentation – exemplify the point of different types of documentation for different purposes.
Low-level documentation
You will often hear low-level documentation referred to as “inline documentation” or “code comments.” And these names describe exactly what they are: comment lines within the code itself that explain exactly what those specific lines of code were written to do. For example, next to a function declaration, an inline comment might explain what the function does, its parameters, and possible return values. Another common usage for code comments is to explain the reason for a specific line of code.
What is inline documentation expected to achieve? A code comment explains specific lines of code in and of itself, within the relatively isolated context of precisely where it’s written. As long as we remember that this is their point, we can see that well-written and well-placed code comments can do their job quite well. Because of their very nature, code comments can’t provide the bigger picture. For example: what does this line of code do as part of a complex architecture or within the broader logical flow?
High-level documentation
High-level documentation’s name tells it all. It provides a view from 30,000 feet up. This is the type of documentation that often includes descriptions of code architecture, data flow diagrams, business logic, and the reasoning behind specific code design decisions. It might also contain descriptions of whole repositories or its main modules
Like low-level documentation, high-level documentation can do the job it was designed to do when it’s well-organized and well-written. But while it has its uses in describing the big picture, it won’t give developers much in terms of the details they need for their day-to-day work. Meaning, that if your high-level documentation is describing the general process, your documentation will only be effective up to a point if you’re not also including specifics with details and examples from the code.
The third type of documentation: Walkthrough Documentation
The missing link in the documentation world between low-level and high-level documentation is what we refer to as Walkthrough Documentation and it is often overlooked. But the truth is that Walkthrough Documentation is where most of the action is… and where most of the value lies.
Also true to its name, Walkthrough Documentation takes its reader on a guided tour of the codebase, often using code snippets to explain points of interest on the map. As it moves from landmark to landmark, it can point out recurring patterns, or describe interactions between different blocks of code that may reside quite far from each other or even multiple repositories
As we take a closer look at Walkthrough Documentation, we’ll quickly recognize that it has many other potential uses. But first, let’s take a look at each of the two major examples mentioned above.
Recurring patterns in code
Every repository contains patterns – things that repeat many times in our codebase across different files, e.g. deriving from a base class, calling a specific API to read from a database, creating a new config value, adding a new CLI command, etc. An engineer entering the team will probably at some point need to perform one of these tasks and will need to understand how they’re done in your codebase. Understanding this could be very easy if the patterns are simple. For example, it just entails calling a function (reporting an analytics event by simply calling a function can also be considered a pattern).
Alas, however, many patterns are not that simple and span many different, often far away files in your codebase and can be tricky to understand on your own. These kinds of patterns evoke the need for Walkthrough Documentation.
Let’s look at a specific example – adding a new CLI command. Specifically, with git CLI, let’s say that you want to contribute to the git project by adding the command `git mycmd` and you want to understand how such a pattern is achieved in git’s source code. Here’s a quick walkthrough overview that shows the required steps without going into too many specific details. Just to prove our point, no specific C-language knowledge is required.
To learn how new commands are created, we’ll take a look at the `git clone` command, a pre-existing example of this pattern. We can see that this command, along with every other command, comes with a corresponding file in the `builtin/` directory (in our case `builtin/clone.c`) and contains the function that implements the actual command.
We don’t need to delve deeper into this function in order to get a grip of the pattern. Note the signature of the function and its name – every command function has this signature, and starts with `cmd_`.
Declaring the function isn’t enough: we also need to declare it in `builtin.h`
Next, you’ll need to “register” the command so that git will know where to find it. Do this by adding it to the `commands` list of structs detailing the commands in `git.c`.
Finally, add the command’s file to our `Makefile`.
This explanation is tightly code-coupled and goes over specific implementation details including how to name functions, where to put files (the `builtin/` dir), function signatures, how to name files (`clone.c`, `builtin.h`), variable names (`BUILTIN_OBJS`), etc.
The explanation walks the user through different areas of the code that are all related to the single pattern of adding a command to the CLI. This kind of highly focused tour through the code can really help the user grasp the pattern and understand it quickly.
This example is still rather small and simple, and larger patterns that span more files will gain even more benefit from using Walkthrough Documentation.
Flows spanning multiple components
Often in real-life software systems, we find that the core logic of the system involves different areas of the code interacting with each other, in various ways that are not always easy to understand. For example, a feature in any modern web-based app spans both the front and back ends and would require jumping between these areas in order to understand the full feature. This can be tricky for newcomers, and a document that puts all of these interactions on a single page with the overarching logic laid out can help significantly, and lay down the foundation needed to understand more interactions like these in other pieces of the code. This becomes even more important if the feature spans multiple repositories (for instance, if you have a repository for the backend and another one for the frontend).
Why is Walkthrough Documentation important?
Walkthrough Documentation fills the gap between low-level and high-level documentation. For a new developer on a team (or an experienced developer working on new sections of the codebase), this type of mid-level documentation is invaluable and has a direct impact on his or her day-to-day tasks.
In our new reality of remote work locations and globally-dispersed teams, onboarding often happens remotely. There’s no one sitting at the next desk to call over and answer a question. And even when onboarding happens face-to-face, the time investment required of an experienced developer to bring a new developer on board can be enormous.
In these situations, while we recognize that documentation can never completely replace real one-on-one interaction when onboarding new team members, well-created and up-to-date Walkthrough Documentation can actually save countless hours when companies are scaling.
Consider also what might happen if the developer who originally wrote the code leaves the team. In the absence of this type of detailed, mid-level documentation, such a departure could leave a huge knowledge gap – potentially demanding months of tedious code exploration to recover.
And even beyond onboarding and employee turnover, Walkthrough Documentation can help to remind the future you (3 or 6 or 12 months from now) how and why you wrote a specific piece of code the way you did. And you deserve that support!
Walkthrough Documentation challenges and how to meet them
So now that we recognize the inherent value of code Walkthrough Documentation, let’s think for a minute about the reasons it might be so often overlooked.
- It takes time. Yes, it’s true. Like so many other valuable things, creating Walkthrough Documentation requires an investment. But the time investment required can be minimized if you create your Walkthrough Documentation when the knowledge is fresh and if you use the right tools to make it easy. For example, using Swimm allows you to select the code snippets, and organize and describe them in a way that’s intuitive and fast.
- Its value is lost if it’s not maintained. Because the content of Walkthrough Documentation is so tightly coupled to the code itself, if the documentation isn’t maintained as the code changes, it loses its value (or might even cause errors). Fortunately, Swimm makes it easy to practice Continuous Documentation as part of your development cycle – automatically keeping code snippets and references up to date as the code changes.
- No one even knows it exists. Even though Walkthrough Documentation is so tightly coupled to the code, unlike inline documentation, it doesn’t live inside the code itself. As a result, it can be missed exactly at the moment it’s most needed (while you’re working on the section of code it relates to). But it doesn’t have to be that way. Swimm indicators in your code make it easy to see when relevant documentation exists and allows you to open it right inside your IDE.
Creating Walkthrough Documentation that describes processes, flows, and interactions – in our estimation should be a requirement because it’s that important.
Bottom line
By filling the gap between low-level and high-level documentation, Walkthrough Documentation provides enormous value – both in onboarding new developers to your team and in the team’s daily work. But the only way to unlock the enormous value of Walkthrough Documentation is to create it, and then, of course, maintain it!
Swimm makes it easy to do just that. Experience Continuous Documentation for yourself: live code snippets, auto-sync, IDE integrations, and more. Sign up for Swimm’s 1:1 demo and become part of our growing developer community.
