Documentation as a practice has a depth that might surprise many software developers. If you’ve ever observed documentation as something consistently lacking, but it never seems to improve, it could be because your team is still visualizing what good coverage needs to look like. In this article, we are going to talk about 3 different types of documentation: Low level documentation, walkthrough documentation / Mid level and High level documentation.
When someone expresses that they feel like the documentation is lacking for a project, they could be referring to any one or combination of several kinds of documentation. As being able to identify what lacks is key to a successful strategy, we’ve put together this summary that we hope you’ll find helpful.
If we take anything at all away from this, sparse documentation of any kind is obviously better than no documentation, as long as it’s up-to-date. While there are some purely functional demonstrations of language features that require no documentation to understand, our position is that almost no code is ever guaranteed to ‘explain itself’ to your future self, and writing something down should be done when it’s fresh.
Code comments save lives. Your low-level documentation helps make clear what the code does, or at least what it’s supposed to do. This takes the form of structured Oxygen or similar formats, or just a quick note to your future self and others that need to learn it.
This is tactical documentation aimed at making sure you know what is happening within the code. You know what the methods require, you know what the methods return.
Mid-Level / Walkthrough Documentation
There are two more important questions that come to mind when you think about wrapping your head around new code - you want to understand why you use it, which also lends itself to when you need to use it. This exists in a few common places:
- Swimm docs (and playlists) that give a guided tour of code, or a step-by-step demonstration of how and when code should be used. This is also that lengthy explanation about that odd-looking state machine, or algorithms that are just too formidable to explain in the laconic space that code comments provide.
- Detailed README files that give an overview of what’s in a certain directory (or branch) of the code, along with instructions on how to build, what dependencies are needed, or other mostly procedural metadata about the code base.
- Curated or generated changelogs that help explain how the code evolved.
When you read mid-level stuff, it’s usually because something in the code alerted you that more information was available. If you’re using Swimm and one of our IDE plugins, this happens automatically - you’ll see references to any Swimm documentation right where the code lives. If it’s not in Swimm, you’ll generally see “/* see docs/caching/README */” or similar as a breadcrumb.
The big picture. This is a transcription of the notes you wrote on that napkin when you and the other two founders came up with the idea at the taco joint. The product value proposition, the business logic, the rationale behind various choices that went into the stack that you now use, the user journey stories based on the market that you serve - all of the stuff that helps anyone internalize and understand the overarching goals that everyone should be working toward.
This exists in whatever the company used as an internal wiki when it started, and was probably copied to different platforms as teams figured out what tools they wanted to use. Most companies have this, but very few actually keep it up to date as the relevance runs dry.
To make your walkthrough documentation automated and streamline it as part of your agile development process, try Swimm. Swimm integrates with the IDE and CI pipelines, making it easy to document on the fly. Beta access is now available here.
Happy documentation 😀