I have believed, up until now, that the best way to learn a codebase/team processes/etc is to either A) learn it yourself through study or B) have someone verbally explain things to you.

Written documentation has not been high on my list.

I think I’ve been wrong.

It occurred to me today that I didn’t know why I was against written documentation, so I explored my thoughts about it. This article is what I came up with after thinking it through, and my conclusion that written documentation is a much better route for many situations.

Is knowledge transfer needed?

For the sake of this article, let’s assume the answer is YES. If the answer is NO, then the rest of this article wouldn’t matter.

What is the best medium for knowledge transfer?

                          | Verbal | Written | Video 
 -------------------------|--------|---------|------- 
  Ease to change          | √√     | √       |       
  Up to date              | √      | √       |       
  Quality                 |        |         | √     
  Scalable                |        | √       | √     
  Ease to produce         | √      | √       |       
  Waste if not successful | √      | √       | √√

Video knowledge transfer would be awesome, but it’s not realistic. It’s very difficult to update when changes happen, and not easy to produce. While it would be nice to have, let’s take that option out right away to simplify things.

Now, let’s explore just a few of the pros/cons of other aspects:

Ease of change and up-to-date

Verbal wins. Your brain is usually more up-to-date than any written documentation, and as soon as you learn something it’s updated in your brain. Written documentation is not hard to change, it’s just hard to remember to change.

Scalability

Written wins. One person can write an article that 12 others read on their own time. Scalability may not be important if you’re in a company that hires one developer every 8 months. My team happens to hire much more often than that, making scalability an important factor in this decision.

Waste if not successful

We may do a great job on getting initial documentation up, but then fail to maintain it. Or, we may lose steam and not finish the initial setup. It feels like it would be such a waste of work if your written documentation doesn’t get utilized, right?

But, let’s say that it takes you twice as long to write documentation as it does to pass knowledge along verbally. Before you lose steam and your documentation isn’t maintained like it should, two people have read it and benefited from your documentation. You’re at least as even at this point as you would have been had you relied only on verbal knowledge transfer. If you maintain written documentation even half well, and get two more people through onboarding with your written documentation, you’re at a profit for the effort.

Bottom line is: the “risk” associated with trying out writing documentation is at least as risky as verbal knowledge transfer, with the potential to be a lot more successful.

Imposter syndrome

This is tough to quantify, but there has to be a certain amount of a “wow” factor that a new teammate must feel if they enter a team that has organized and well-written documentation. They will be impressed. There won’t be a sense of “how am I ever going to learn what I need to”, or feeling swamped in a land of tribal knowledge. Please empower/encourage/beg new teammates to update the documentation as they go through it for the first time — they’ll feel ownership over the team’s area faster as they do this as well.

So then, is written documentation worth it?

I think it’s worth getting good at writing documentation. It will be at least as profitable as verbal knowledge transfer, but has greater potential to be more scalable, peer reviewed, and impressive.

Next steps

How do we go about starting this in a team or company?

I think there are 2 phases for each area of documentation: setup and maintenance phases.

Setup phase

This is where you write the initial documentation, after doing the research needed to write it accurately. Peer review would be a great idea to improve quality and to do some knowledge transfer in the process.

Initially, you may propose setting up a calendar invite for your team to take two hours each Friday for documentation work.

Maintenance phase

I think this is the part that I’ve been missing all along. Written documentation can be up-to-date — if you keep it up-to-date! Make it a habit for your team to take one hour each sprint to update documentation, or to improve existing documentation. Make sure the steps are clear, write better summaries, include diagrams or screenshots, etc. Bake it into your sprint, and have it be a recurring calendar invite.

Summary

In an increasingly complex world of software systems and large repositories, it is daunting to enter into a new team without any context. Having written documentation will enable faster onboarding and morale through that process. Creating documentation and maintaining it is not as bad as it may seem, if you consistently take small amounts of time to do it. Doing so is the most scalable solution for transferring knowledge.