TL;DR: I'm excited to announce that I am joining Twitter to focus full-time on documentation and open source.
Background
Living in Portland, I'm lucky to be surrounded by some amazing people. If you wander down to the food carts on any given weekday at lunch time, you're likely to run into any number of luminary 'people from the internet' hanging around.
One of those people might be Eric Holscher. I've known Eric since 2011, mostly as a towering wookie-like figure with killer ping-pong moves that is also an insightful Python developer. I was vaguely aware of his side-project, Read The Docs, which, since 2010 has been a vital resource to the Python open source community.
As a developer, I have always cared about documentation, but I'm not sure I ever thought about it deeply until I got to know Eric Holscher better. Sometime in early 2013, I ran into Eric at a local eatery, and we started discussing Read The Docs. He had recently left his job at Urban Airship and was able to work on Read The Docs full time. This was going well, but he was concerned about the future of the project. There didn't seem to be a sense of community around documentation. Was documentation ever going to be given the focus it needed?
At the same time, I looked around me and realized that here in Portland, I was surrounded by some amazing people working with documentation; Noirin Plunkett, Luc Perkins, Leslie Hawthorn, Adron Hall, Joe Moon, Eric Redmond. I saw a community that didn't see itself.
Eric Redmond was the first person I'd met with the (self-appointed) job title "documentarian".
Building a Community of Documentarians
I have a habit of starting conferences, as well as local meetups, and creating terrible inside-joke-esque slang. I really enjoy helping people organize to create the things they want to see happen.
Naturally, my first reaction to Eric Holscher's existential angst about docs was, "Let's have a conference". I called up Eric Redmond and we had our first meeting of documentarians (I refer to them collectively as "the Erics").
There exists a tribe of documentarians in the world. Up until this point, they haven’t had a central place to meet each other, and coalesce into a community. We are providing the space to allow this to happen, both in person and online.
The headline quote above is from a doc, then titled "Write the Docs: Manifesto", written that night. The Erics almost laughed the idea off at first; no one would come, no one would sponsor it. I said "no really, it's not that hard, let's see what could happen" and bought another round of beer. So, we created a landing page with minimal details, included a call to action and a mailing list signup form, then posted the link to Hacker News.
It seems we touched a nerve.
Originally, we were discussing a 50-100 person conference, mostly made up of local Portland people, probably mostly developers. Instead, we had hundreds of signups for the mailing list in the first day. Over the next couple months we were contacted by people from a variety of disciplines; technical writing industry groups, designers, typographers, literate programmers, API driven startups, and more. We quickly found a new venue, and sold out a 250 person conference. The experience was amazing. We'd found our tribe, and they'd found us.
Now, we're ramping up for year two, with conferences both in Portland and in Budapest this spring. We've seen local meetups spring up in San Francisco, Boston, and New York. We're working on building more.
What's a Documentarian?
During my interview at Twitter, one of the questions I was asked was:
"What unique skill does a documentarian have that is distinct from a developer, technical writer, etc?"
At the time, I was a bit stumped, and sort of rambled out something about focusing on docs as a priority… but that wasn't really it, and the question nagged at me. In the following days I crunched on it in my back-brain, and eventually came up with a slightly more coherent answer.
A documentarian is someone who wants to share something with someone, looks at a blank screen, and knows what should be there.
A documentarian uses the tools of code, technical writing, and visual design to create engaging learning experiences that work well for a wide variety of people.
A documentarian is more than an intersection of skills; it's someone with empathy for the learner, and a unique vision for the accessibility of difficult topics.
A documentarian does more than describing what's there; they explain how to use it in a way that you can understand it.
Culture Change: Agile, TDD and Documentation
Those of us with long enough memories remember a time in developer culture when writing tests was scoffed at. It was something only crazy people really cared about. Unit tests? I guess, if you have extra time, and are extremely particular… This all changed.
Agile made us realize the error of our ways. Someone slid TDD, test-first development, and CI/CD into the cultural forefront.
Nowadays, if you release code without tests, you feel ashamed of yourself. People agonize over their code coverage, and slavishly attempt to please the TravisCI test runner. They wear their passing builds with a badge of pride on the front page of their open source project pages.
But one thing always bugged me about the Agile Manifesto:
Individuals and interactions over processes and tools
Yes!
Working software over comprehensive documentation
Huh?
Customer collaboration over contract negotiation
Yes!
Responding to change over following a plan
Yes!
Why was documentation derided in this manifesto? How are those two things even related? Who spends time documenting broken software? But this is number two on the Agile Manifesto's hit-list of problems to solve.
The ostensible reason for this is upfront documentation. Writing up design docs about a software that you might make, instead of just making it. We can all thank Ward Cunningham, Alastair Cockburn, Martin Fowler, and many others for changing the status quo in our industry. The standard of the nineties is no longer the norm.
Unfortunately, for documentation, it went a bit farther in the minds of the General Public™.
That rule in the manifesto translated to "documentation takes time"; too much time? Hmm.. So does writing unit tests.
Well, ok, but it's really because it gets out of sync with code so easily? Yeah but, so do unit tests.
Both unit tests and documentation are often sticking points for people trying to understand the agile way of doing things. How does one stay agile, but also write tests, and create excellent docs?
People have tried to write off this problem many different ways, Ambler's JBGE ("Just Barely Good Enough") and Cockburn's *Crystal Clear* method's "just enough documentation" being the most popular takes. So, what exactly is the MVD (minimum viable documentation)? When does it cross the line from "barely good enough" to "comprehensive", and why is that a deal breaker?
All of this sounds like a tooling problem to me. Takes too much time? Build a tool to make it faster and easier. Gets out of sync with code? Build a tool to help keep it in sync.
*It's my goal to see the development culture around documentation change just like it did more than a decade ago with Agile and TDD. *
The time for all technical people to care about documentation is now. We’ve lived too long with awful instructions for the tools we use everyday. People should demand solid instruction of things that they use.
I believe it should be easy for people to start writing documentation. There should be straight-forward guides to getting started with good tools.
I'm going to make that happen.
Why Twitter?
I feel that Twitter is the perfect place to launch this revolution. Twitter cares about documentation, and has a significant docs problem. They have one-thousand (1000) developers, and three (3) technical writers. They are an API driven product. They have released a wealth of great open source tools. They care about communication; it's their core value proposition.
It's a big enough place that it will be hard to solve their problems, but small enough that I might actually be able to do it; then translate my experience there to the rest of the world.
So, my first goal will to be to ensure that Twitter has the best documentation in the world.
Along the way, I'll build open source tooling to make that possible, and help other organizations achieve the same level of excellence using those tools.
After everyone in Twitter cares about documentation as much as I do, I'll switch my role over to "Open Source Advocate", and share our success with the rest of the world.
I'm excited to become Twitter's first documentarian, and I don't expect to the be the last.