Enabling Teams to Write Strong Documentation
Part 1: The Journey
I love to write documentation.
I’d like to claim that I’m motivated by noble reasons like sharing knowledge and growing talent, but honestly I just hate to explain things more than once. Writing quality documentation ensures the availability of information that might otherwise exist only in my head. It reduces the frequency with which I have to repeat myself. It means fewer interruptions while I’m on vacation. It enables us, as a team, to scale more efficiently by reducing the time needed in-person to introduce new developers to our codebase.
Unfortunately, we haven’t always been great at writing documentation.
This will hardly come as a surprise. Many developers dislike writing documentation; it’s boring, and hard, and feels redundant after you’ve just written the code. It’s easy to assume your own code meets the ideal of self-documentation when it’s still fresh on your mind. Unfortunately, that ideal doesn’t always hold up when you come back six months later, or when another developer digs into your code.
For a long time, I attempted to tackle this problem simply by asking people to write documentation. While I had some success, this never worked quite as I had hoped — even when the team was small. So I eventually gave up and just started writing the documentation myself. Here I ran up against several problems; hard to read code, logic scattered across multiple unlinked files so that it was impossible to track, developers unavailable because they’d moved on or were too busy to assist. I also had my own work to accomplish, and writing all the documentation myself was far from scalable as we grew.
So I returned to asking people to write documentation, now with bonus passive-aggressiveness in creating empty documentation files and tagging people on them. Desperate times…
We continued in this state for a while, with some developers dutifully contributing to documentation and others ignoring it entirely, while my frustration mounted. Eventually, in a 1:1 with my manager, she asked (only sort of joking) “Well, can’t you just teach everyone to write documentation like you do?”
YES! Yes I could! Probably.
I began my research by reading about a billion and one articles (your mileage may vary, but I’ve linked a few of my favorite reads). I spent time working on a presentation for a lunch & learn on writing good documentation, but still something just felt off about my work. I started more drafts of this blog post than I’m proud of. I had all these suggestions for best practices and places to begin, but nothing real or concrete on how to just sit down and write good documentation.
Then, during a long lunch break sitting by the lake and roasting all of my frustration away in the sun, I realized that I was asking the wrong question. I was asking, and aiming my research at answering, the question of how individuals could learn to write better documentation. But many developers don’t really want to learn to write better documentation — they just want it to be easier to write documentation, period!
What we needed was not a series of lunch & learns on how to write good documentation, but a system enabling developers to write documentation as quickly and painlessly as possible.
And so the first phase of my journey in building a system of documentation for our team began…
(To be continued in Part 2: The System)
