From Couch to Continuous Documentation: Incorporating Documentation into the Development Workflow

If you’re reading this, chances are your software team/organization have been discussing at least a few of these pain points:

1. The long and complex process of new hire onboarding - Getting a new developer fully ramped up takes 3 to 9 months on most teams. Decreasing this time can have a huge impact on your team’s velocity.
2. Problematic knowledge silos – Though silos were initially formed for a good reason (to help engineers on your team develop expertise and focus), now they are more likely creating bottlenecks, business risk, and/or making it very hard to change your organizational structure.
3. Super complex code that slows you down - That huge and scary pile of code was written long ago, only a few truly understand it, and everyone’s afraid to touch it. Unfortunately, it’s also an essential part of your product, and many people on the team need to interact with it.
4. Risk of attrition – The scenario we fear: what happens when one of your senior developers - the only one familiar with a certain aspect of the code - decides to leave the company and pursue another opportunity.

If you’ve read about Continuous Documentation and Walkthrough Documentation and thought, “Finally, here’s what I was looking for, a way to address the problems listed above,” we’re proposing a step-by-step version of exactly how to do it.

Here we won’t focus on high-level documentation or the specificity of what’s in the code comments you write, but rather ways to make Walkthrough Documentation a part of what you do.

The path to Continuous Documentation

Whatever your relationship is to documentation, we promise you there’s an “in” to get hooked on it.

Much like the classic portrayal of the couch potato with high cholesterol who wants to be that person that runs a few miles every week but doesn’t know how to get started, you need a gradual plan to get from your couch to the “5K Code Documentation jog”.

So join us in getting off the couch and starting your documentation run.

Scenario 1 -  the couch potato who has few or no docs

Does this sound like you?

1. You started off in a small team and didn’t really need documentation.
2. You had to build everything quick-and-dirty to meet a deadline at some particular point.

If this sounds familiar, first of all, don’t feel bad; you’re definitely not alone. Many other teams and projects are in the exact same situation and do not have any documentation at all.

But now you realize that without documentation, it will become increasingly hard to scale up your code and your team.

What you need at this point is to create a critical mass of documentation that will show you and your team the potential value of walkthrough documentation.

Start with the low hanging fruit

How to start? Look for low-hanging fruit – creating documentation that will be of significant value for the team in the short term, without too much effort. These could be documents explaining:

• the structure of your source files
• coding guidelines and best practices
• how-tos on how to write tests
• connecting steps to the CI flow 

What does “without too much effort” mean? In our experience, creating a critical mass of documentation should take one experienced veteran developer in your team 2-3 days to create. Of course, you can split this between several devs as well.

If you find yourself staring at a blank page - unable to decide how to start a document, here’s a method that always helps with documentation writer’s block: first, just add all the code snippets of the process/flow/module you want to describe. Next, put them in an order that makes sense. Then just write a few words about each one of the steps/parts. Finish by writing an introduction and summary.

You'll be surprised at how easy this process becomes.

Easily discoverable and up to date 

Now what? To make sure this documentation has the intended effect, you need to have it readily discoverable and available for your team. You can save it as Markdown in the relevant place in your repo or manage it on a documentation platform in a way that’s highly intuitive to search.

You also want to make sure your documentation remains up-to-date as the code it relates to changes. To do so, you need to add a step to your code-review processes. Specifically, having the documentation as Markdown will make it easy for reviewers to see if changes in the code are also accompanied by the proper changes in documentation.

Scenario 2 - the occasional code documentation jogger

Does this resonate?

You’re not ready to have documentation as an integral part of your development workflow yet, but you do have some documentation already - and your team already understands and acknowledges its value.

Start with a “Docuthon”

Since you’re not going to be documenting on a regular basis yet, you can’t afford to take small steps when you do. A good solution for you is “Docuthons.” Much like hackathons that some teams practice every once in a while to get the team to cram a lot of work and help each other while they’re at it, Docuthons can help you cover a lot of ground in bursts.

Again, you should focus on documentation that will bring significant value to your team and efforts. Try letting the devs on the team come up with the best things to document, to get them fully on board. Here are some other examples of things you may want to cover:

• an old tech stack that not all team members are familiar with
• an area in the code that is prone to errors,
• lessons learned from previous customer escalations 

So, order some pizzas and beers, put on some energizing music, and document away!

Oh, and if you haven’t put in place something to make sure documentation is easily discoverable and updated, be sure to do so now.

Scenario 3 - the code documentation runner

Is this scenario familiar? 

You’ve accumulated a fair amount of documentation. Most of the devs on the team are totally onboard with the idea that Walkthrough Documentation rocks, and now you’re ready to introduce documentation as an integral part of your development lifecycle. 

Start with documentation tickets

Now is the time to start creating and maintaining documentation tickets and adding them to your technical debt backlog. When you can spend some time working on your technical debt, make sure you take care of some of these tickets.

Here’s the question, though: how do you know if your team is adopting this?

The answer: when documentation tickets make up more than 10% of your backlog and more than 20% of the tickets that are selected when the team chooses what to work on next.

Don’t be afraid of adding relatively small and easy documentation tickets, like:

• how to add analytics or events to your code
• updating design documents to reflect the latest status of the code
• knowledge sharing across all team members on disaster recovery drills, etc.  

See documentation climbing to more than 50% of the backlog? Check to see if the tickets are impactful and clear. Also, you may need to plan a Docuthon soon…

Scenario 4 - the code documentation 5K sprinter

Is your team experiencing this?

Documentation is already viewed by the team as an integral part of your technical debt, and you are ready for the next step: making documentation a constant habit. Since you’re making changes and adding features in every sprint, it makes sense to include documentation tasks in every sprint - or at least in most of them. 

Start with documentation tags

When the team is planning the sprint, make sure to add a documentation tag to every ticket that includes changes or additions that are complex or important enough to justify documentation. If possible, be sure to also include some documentation tickets from the technical debt backlog as well.

To determine what's important or complex enough for documentation, ask yourself this about relevant tickets: 

• Will there be something that we learn in this sprint that is worthwhile sharing with other team members?
• Is the information about this task public knowledge, or is it worthwhile to echo it beyond the team’s boundaries?
• Will any knowledge that will be essential to future contributors be lost if we don’t document it?

Bonus scenario – off to the Continuous Documentation marathon

You’re so close now. Here’s what we mean: you’ve already met two of the three conditions for Continuous Documentation.

1. You’re creating code-coupled documentation and
2. You’re making sure it remains up to date as the code changes

To get to the marathon, make sure that documentation is created at the most opportune time. The goal is to get documentation to become an essential element in writing code. 

In a sense, Continuous Documentation and coding become one. This will sometimes mean writing the documentation before you start the development of a new feature, documenting how to troubleshoot a bug in production right after you’ve fixed one, documenting a module while you’re refactoring it, and more.

Bottom Line

The gap between no or little documentation and adopting Continuous Documentation is far-reaching and consequential. No team can make that jump in one go. Moreover, attempting to do so will likely lead to a lot of frustration and doubts about the long-term value of documentation.

Part of bringing your team onboard with Continuous Documentation is helping them get off the couch and motivated to sign up for the Continuous Documentation marathon. Trust in the documentation process - its value needs to be built up and modeled in increments. Gradual and deliberate should be the operative words here. That is, don’t take your time too much because the best time to do code documentation is when it’s fresh in your mind, and you’re thinking right then and there exactly what you want to remember.

In our experience at Swimm, moving to Continuous Documentation can be done in just a few months. Throughout that period, make sure that documentation is kept up to date and is as widely accessible as possible. This will make the process faster and smoother. Because ultimately, your documentation’s intrinsic value and the amount of time everyone will save will be the best motivator to get your team off the couch.