Write the Docs: Amalia Hawkins – Ignorance Is Strength: Writing Documentation By Learning As You Go

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Amalia works at MongoDB as a software developer. Traditionally in documentation we want to spread knowledge. Ignorance is the enemy. Ultimately, though, the struggle that comes in overcoming ignorance is one of the strongest feedback loops for quality documentation.

When Amalia was hiring TAs while working in college she learned that the best TAs were frequently those who got Bs and Cs in the course; the ones who struggled with the material themselves.

When she started at MongoDB Amalia was faced with learning how to work with a code base approaching 1.4 million lines of code. A lot of that works came in just reading the code and deciphering it. Some could be done by looking at user-facing documentation and learning how the product performed in an end result. At a certain point, though, all those strategies fall short. Reading the code can’t tell you the internal mechanics and design decisions that went in to building it.

https://twitter.com/foxesinsockses/status/463382706881966080

When reading the code falls short a lack of internal documentation hampers a company’s ability to scale. It causes growing pains across the board. It also impacts hiring as your new hires take longer to become productive within the company. Opening new offices and scaling horizontally also becomes difficult when you don’t have internal docs and best practices for self-learning.

While you don’t want to push code that is inherently wrong you can start with rough code. Even if it’s wrong it gives someone a hook to come in and offer feedback. For Amalia this took the shape of a 1,300 word rant about working with a particular aspect of the code. She sent that rant to the two people most familiar with that part of the code. The response was really positive; there was actually a large audience of people frustrated with the same problems she ran in to. Other people said, “Wow, it’s great that someone wrote about this. It’d also be great if someone wrote about these other things.”

The trick is that you need to find your allies. Find those other people who are as confused as you are; there are always those people. Those same allies can help you spread the work out. It makes you not the single point of failure. It also lets you take the burden of writing off of the engineers developing the code. If you enjoy writing others will enjoy you taking it on.