I first heard about Write the Docs conference, held in Portland, OR, on April 8-9, on the TECHWR-L email discussion list. But when I first looked at the conference schedule, I thought, “Wait, not a single name involved sounds familiar. Who are these people?”
With a little more investigation, and as became abundantly clear during the actual event, the organizers and speakers at the Write the Docs conference are, in large part, open source developers, who along with many of their open source compatriots, fervently advocate on behalf of their users and the open source community. These folks believe that documentation is essential. Python is a native language to many in the open source community, and Portland seems a hotbed of open source developers and open source companies. Armed with answers to the who, why and where, I headed off to Portland to get to the heart of the what and the how of creating a culture where documentation is valued.
Most of us claim to know real-life examples the stereotype of the uncommunicative software engineer, who is totally uninterested in good documentation. Well, the software engineers at Write the Docs disproved that stereotype over and over again. In the open source world, with hundreds and thousands of contributors, every change has to be well-documented, or very soon nobody knows what is going on. One presenter lamented how his Python framework was later overtaken in popularity by a different, better-documented one, and he took full responsibility. Another, Kenneth Reitz suggested that you first write the ReadMe and the API documentation, and then develop the API. The absolutely critical nature of documentation came through again and again.
Tim Daly, an ex-IBMer, who self-identified as “old,” talked about how he came into possession of Axiom, a computer algebra system. Created by IBM, Axiom is a powerful system that contains algorithms that are not available anywhere else—it was more than a million lines of undocumented code when Daly acquired it. Axiom is now an open source project, and contributors are doing their best to expose its virtues. The lack of documentation and project organization of the original Axiom cost IBM hugely, as they subsequently went to ridiculous lengths to replicate what they already had.
The Agile Manifesto contains the maxim to value “Working software over comprehensive documentation”. To these developers, this makes no sense, as documentation is seen as part of the software deliverable.
From what I could tell, the conference was split between these groups of attendees:
- Software developers, who came in large part from the open source community
- Technical writers, mostly with a strong technical bent
- Project and product managers
- People in various ancillary roles related to Web and software development
We heard from presenters from Google, Mozilla, PuppetLabs, SalesForce, and many other “happening” companies. Some topics included:
- Inculcating a culture where engineers see documentation as their responsibility.
- Creating empathetic, irresistible documentation, even, or especially, if you are talking about APIs. The concept of empathy was mentioned again and again. These people care about their users!
- Literate programming, based on the ideas of Donald Knuth, who was a huge inspiration at this conference. This is code written to be read. The idea is that you start with humans explaining to humans, and then make it work for the computer, rather than the other way around.
- Practical topics like how to manage documentation development and distribution at Google’s scale, and the problems that can arise when documentation development processes are in fact unscalable.
Ana Nelson’s talk garnered a huge amount of attention for DexyIt, described as “Open source software for software documentation, reproducible research and document automation”. It was the last session, and I missed it due to travel, but the excited tweets made me regret my early departure.
For those that missed the conference and want to learn more about Write the Docs, several attendees blogged some good online synopses:
- Jennifer Hodgson (who presented on API documentation in the Drupal open source project): http://poplarware.com/news/writethedocs
- Andrew Nhem: http://auralest.com/write-the-docs-2013/
- Andrew Spittle wrote up several sessions in detail: http://andrewspittle.net/
And just look at #writethedocs on Twitter to find pithy summations of the main points.
This was the first Write the Docs conference, but more are planned. It will be a conference on my list of must-attend events in 2014.
