Something really neat about working with Swimm is the constant challenge to really understand fluidity when it comes to being a tool that’s designed to integrate in a huge variety of processes. That’s a big concept to chew on, so let’s break it down – in order to earn a spot in the top compartment of your developer toolbox, Swimm needs to:
- Integrate with your IDE, so you can discover and read documentation right when you need it
- Integrate with your continuous integration server, or other build scaffolding so that your documentation can stay tightly coupled to your code
- Integrate with your team’s documentation workflow, so that documentation actually gets written
That’s already quite a bit, but there’s another big integration that Swimm needs to achieve – it needs to integrate with your personal writing workflow and style. Our success is directly correlated to your success in writing, so how teams approach their documentation challenge from a tactical perspective is of great interest to us, and something that we heavily study and research.
Our clients and design partners have given us amazing feedback over the last year of our private beta and (surprisingly or not) an appreciable source of apprehension for early adopters didn’t have anything to do with product features – it had more to do with figuring out how to approach a big ball of mud with an eye for documenting it. While everyone does things a little differently, folks were mainly utilizing one or more of four fundamental strategies. As this applies to documenting code with any tool (we do hope you’ll try Swimm!), we thought we’d share these main strategies and our thoughts about them.
This is part of a series of articles about what is documentation.
Everything below is in addition to code comments.
The “firefighter” approach
You write documentation when questions arise, and expand it when more depth is needed. This is the most common approach and works best if followed from the beginning. Other things can trigger this as well – like when you find yourself writing a code comment that’s getting too long. While the name conveys a little chaos, this is often a planned approach.
Make sure to set up smart triggers for docs getting created, beyond people pointing out a lack of them. For instance, you can say that if more than two people are going to work on fleshing out an idea, it needs to have some kind of documentation telling others what it’s about and where it’s at. Not only will this help you down the road as it solidifies, it makes your organization more inclusive by eliminating needing to be part of an ‘in’ crowd to know what people are working on.
The depth-first approach
You explain a single, or very few things in very great detail. This method entails writing not just tactical – mid-level documentation, it also warrants high-level perspective passages as well. With this approach, you’re essentially doing your best to ensure that the reader will walk away with roughly the same level of topic knowledge that your organization has.
This is very common for user-facing documentation that isn’t automatically generated, and a good idea to employ internally for complicated systems, microservice flows, etc. Offboarding should definitely trigger someone to take a look to see if the person leaving has rare knowledge that should be documented in this way.
Learn more: Read our guide to continuous documentation.
The breadth-first approach
You write a little bit about a large number of things. Your goal is to anticipate the most obvious needs and make sure they’re covered, and then iterate as additional clarification and explanation is needed. A common use case for this approach is making some, or all of a code base available to the public. You write documentation for what you think they’ll be doing with the code, and plan on “fire fighting” as needed once it’s released.
This is likely the most efficient way to approach a largely undocumented code base. If you inherit one, this is probably your best bet – just write docs as you figure things out. This isn’t the most useful strategy if you’re trying to stop knowledge leaks at off-boarding unless it’s guided by the task-oriented approach.
The task-oriented approach
How do I set up my local build? How do I debug a service that’s too big to run on my laptop? How do I add a new site setting? All of these are questions that will likely take you to multiple places in the code base and this is one of the places where Swimm is uniquely suited.
This approach is really just a guided breadth-first approach; as you document your way through accomplishing most of the things that are best explained in a tutorial voice, you naturally end up with a respectable level of coverage.
At the minimum, you can write some documentation on how to build, hints and tips on debugging, and anything else that someone new to the code base would appreciate if they had to ramp up in a hurry.
Using this for off-boarding is ideal if you need to make sure that knowledge about processes isn’t lost. Would someone need to know how to prime a cache after a cold start? They’d really appreciate a doc on how to do that if they ever need to learn during an outage.
Learn more in our detailed guide to documentation strategies.
Swimm users: start from a commit SHA!
To make it as easy as possible to make sure new documentation gets introduced with or immediately following large swaths of new code, Swimm lets you set up a document preloaded with code snippets from the files created or changed in a specific commit.
This means all you have to do is discard any snippets that aren’t needed or relevant, and then write a few paragraphs explaining what’s going on in the code, from the perspective of someone new to it needing to understand it.
We’re not done writing about this topic, in fact it’s just the start.
New to Swimm? Sign up for a 1:1 demo to see Swimm up close!
