Thoughts on Transforming Documentation Processes presentation at WTD: Evaluating the trend to treat documentation as code

Summary: Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. You can watch the Transforming Your Documentation Process presentation here: The panelists were Leon Barnard (@leonbarnard), Zach Corleissen (@zachorsarah), Ted Hudek (@tedhudek), and John Bulava (@jbulava). (It’s funny that WTD lists the Twitter handle for each participant – in reality they should list the slack handle of the person on the WTD Slack channel.) Riona started the panel by posing the problem that started her documentation transformation journey at Google. In internal tech surveys at Google, employees noted that documentation was hard to find. When you did find it, it was often incomplete or inaccurate. As a result, you didn’t know if you could trust the documentation (it might be outdated). Riona said the survey’s findings closely paralleled those from the 2016 Developer Survey on Stack Overflow, which found that poor documentation was one of the greatest challenges in the workplace: According to the 2016 Developer Survey on Stack Overflow, the second greatest challenge in the workplace is poor documentation. 50,000 developers took the survey on Stack Overflow. Even if the sample is biased toward people who are inclined to value good documentation (and hence provide informaton / survey responses on Stack Overflow), it’s hard to dismiss the results about the importance of documentation to developers. As more support for the value of docs, a 2013 survey conducted by Programmableweb (which included about 250 developers) also found that “complete and accurate documentation” was the most important factor in an API: Good documentation is the most important factor in an API (As exciting as it is to find these surveys, don’t get too excited – few people seem to take them seriously, as evidenced by the steady decline or flatlining of employed tech writers. But let’s not dwell on that.) The four panelists Riona chose all moved their documentation process toward openness and collaboration in similar ways: Leon implemented Hugo, a static site generator, along with Swiftype for search. In their new model, customer support agents contribute content directly using text editors and commits. Zach at Rackspace implemented a number of open source tools (which process Markdown) to leverage contributions and involvement with developers. The writers at Rackspace process hundreds of pull requests each month from contributing developers. Ted at Microsoft moved toward another open model involving Markdown with a repository. Anyone can contribute docs, and contributing developers have a lively, quick process that seems to have a tremendous momentum. John at Twitter is moving away from their Drupal environment and looking into Sphinx and other similar processes (though he’s still in the conceptual stage). Twitter apparently gave a seminal talk at last year’s WTD conference that influenced a great many attendees to embrace docs as code. Referring to these transformation trends, Riona said there is “change in the air” – you can feel it in the breeze and on the water. Without question, many writers are moving towards a model that treats doc as code, closing the gap between engineering and tech comm, primarily integrating documentation into Github repositories and other code workflows with engineers. The idea is to put docs in a space developers will look at and feel comfortable interacting in. This enables developers to easily make doc updates themselves and fosters more collaboration and community by having an open contribution process. These visionary writers want to move away from the model where only a few technical writers are allowed editorial access into the inner documentation sanctum. But will treating docs as code achieve these technical writers’ goals? With Riona’s model, she says she’s having success. She looks at code commits and analyzes the number of times developers update the readme file when pushing updates. She finds that deve