How I learned to stop worrying and love documentation

Earlier this year, Fusion’s director of engineering Daniel Bachhuber pinged our #tech channel in Slack:


I knew where Daniel was going with this. Developer, document thyself.

Our team previously discussed a similar effort by the nerds at the Institute for Nonprofit News: the Docs repository. INN’s repository was more or less the direct inspiration for our own.

Like INN’s repository, ours wouldn’t just be technical notes and API breakdowns. Daniel wanted the team to document its burgeoning engineering culture in a public repository, using the same pull request workflow core to our product process. Radical transparency, indeed. Though my immediate reaction wasn’t what you’d call ‘enthused’…

tech-docs two

I came around though, and now believe that team documentation (like open source) should be a central tenet of distributed software development. And turns out, documentation has been a lot less cumbersome for the team to implement and maintain than I expected.

If your company or organization has public docs, email it to me!

We’ll add submissions to the list below.

As INN’s senior director of product and technology Adam Schweigert described in an email exchange, “It’s quite easy to get started [with documentation] and not a huge time commitment, but once you have that base to build on it’s much easier to make documentation just a central part of your team/organization culture. Of course, having good documentation is also just the right thing to do.”

Documentation then isn’t just a chore, it’s an ethic, maybe even an identity (the documentarians at Write the Docs would certainly argue such). We work in public as much as possible, yes, but how we work is public, too. DIY kits for replicating culture.

This idea – replicable culture – is at the core of why 18F, an agile product group in the General Services Administration, has embraced documentation in a very big way. As Ben Balter puts it, 18F is the government’s way of saying, “Here’s the best way to build software (and you can too!)”

18F’s sprawling documentation Hub has seen 1,378 commits, 228 closed pull requests, and a whopping 36,125 lines. These are titans of the doc, an organization sharing as it grows. But what are the roots of the Hub? And how does 18F continue justifying the effort?

Former Google engineer Mike Bland joined 18F in November, 2014 as Practice Director, taking responsibility for documentation and training efforts.

“I noticed a stark difference between Google in 2005 and 18F in 2014. 18F was only a few months old, running like gangbusters, and the intention was to help build this ecosystem,” said Bland. To actually build an ecosystem though, first they’d need to scale their team, and to do that, they had to begin documenting early and often.

Hub was the focus of the first working group (‘grouplet‘ in 18F parlance) Bland created at 18F, his first step in helping 18F enact culture change of enormous magnitude.

Bland used a metaphor of trying to feed a hungry nation. An individual, or even an individual group, can’t just plant all the food.

“The trick is, if you figure out a way to plant something, how do you develop that into some sort of abstract and concrete methodology that other farmers can adopt, and create the channel so it spreads not just within your own little farming community, but across the country.”

The task may seem gargantuan, but Bland is no stranger to “big” efforts – during his time in Mountain View, he was instrumental as head of the testing grouplet in retrofitting the Goog’s automated testing culture.

Eight months later and it’s clear Hub has impacted what replicability means for 18F. The onboarding page is best-in-class. As Bland’s colleague Emileigh Barnes (a more recent 18F hire) put it simply, “The documentation was great for me as a human.”

Replicability only begins with new hires though, getting them acquainted with the processes, tools, and culture of 18F. The Hub and its associated guides also serve as a replicable templates – or at least, inspiration – for any organization striving to deliver better digital services, whether within government (the primary goal) or without (a happy accident).

Barnes notes that documentation is just one of a few open node communication tools used by the agency, a stack that also includes Slack and Github – platforms with adaptable, shareable, and archived communications.

Why go through the pain of documenting everything? And more over, making it public?

“I think you have to ask –what kind of organization do you want to be? I can’t speak for 18F, but I think we want to be an organization that encourages discovery and asking questions,” said Barnes.

“The more we share, the more we hear ‘Those are my people’ and they are surprised to find it in government and that brings in a lot of folks, because they see we have a mission and we’re pursuing it in a way they recognize.”

- Ori Hoffer, 18F Communications Manager

This pattern – see people doing cool stuff, ask if you can help – seems to have worked out for INN, too.

“Probably the largest unexpected benefit has been in recruiting. I don’t think we’ve had a candidate we’ve interviewed for a job who HASN’T mentioned our docs as one of the reasons they’re excited to work with us,” said Schweigert.

Feel the same way? Check out the docs and job links below – any of our groups would be glad to hear from you (or accept your pull requests on our docs).

Public Docs

18FDocs, Jobs

Institute for Nonprofit NewsDocs, No open positions but signup to newsletter for future jobs

Fusion TechDocs, Jobs