Wtf is Walkthrough Documentation?🤔

I like to call Walkthrough Documentation the missing link between low-level & high-level documentation. And it's something that is often over looked.

But, in my opinion Walkthrough Documentation is where the value in documenting lies.

So what is Walkthrough Documentation?

This form of documentation takes readers on a guided tour of the code base. It uses code snippets to explain points of interest on the map.

As it moves from landmark to landmark, it can point out recurring patterns. It can describe interactions between different blocks of code that may reside quite far from each other or even multiple repositories

Recurring patterns in code

Repos contains patterns. For example, deriving from a base class, calling a specific API to read from a database, creating a new config value, adding a new CLI command, and the list goes on.

When a new dev joins your team, they will most probably perform one of the above mentioned tasks & will need to understand how they're done in your codebase.

This could be easy if the patterns are simple. But, more often than not patterns aren't so simple and span many different, often far away files in your codebase and can be tricky to understand on your own.

And thus, the need for Walkthrough Documentation comes into play.

Here's an 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.

Take a look at the git clone, a pre-existing example of said pattern. 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 command:

Declaring the function isn't enough: we also need to declare it in builtin.h:

Next up: "register" the command so that git knows where to find it. The way to do this is to add it to the commands list of structs detailing the commands in git.c:

And last but not least, 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.

But there are challenges.

Yes it takes time. Yes value is lost if it's not properly maintained. My colleague delves into the challenges & how you can overcome them in this article.

So, what are your thoughts on walkthrough documentation?