We Are Dev-Docs: Embedded Tech Writing at Puppet Labs
Before I started at Puppet Labs, I was a tech writer at a large corporation (I won’t name them, but their initials are HP). The approach to tech writers there conformed to the traditional "huck it over the cube wall" model I’ve seen at other large enterprises. Anyone who has worked in tech for any time at all has encountered this model, which presents a new product to the writer as a fait accompli and which imagines tech writing as an after-the-fact act of taxonomy: "Here is a thing. The thing has five things stuck to it. Three of those things are red, one of them is made of feathers." And, we're done.More often than not, the huck-it-over-the-wall method results in tech writing nobody reads because it does nothing useful ("I can plainly see that thing is made of feathers, what possible good is this manual going to do me? I'm going to put it back on top of the toilet tank and continue to ignore it."). At the same time, this model creates marginalized tech writers who feel devalued and powerless since the useful contributions they can make are limited to whining after the fact. The diminished value of a tech writer in this approach is underscored by the fact that they are often contractors rather than regular employees. This amplifies the message that we are rented office equipment, glorified copy-making machines.
Sweating With the EngineersUndoubtedly, there are many ways to solve this problem. At Puppet Labs, we solve it by embedding our full-time tech writers in development teams like a BBC reporter in a Gulf War humvee. At Puppet Labs, we tech writers sweat alongside the engineers, we help to bike-shed the UI in marathon meetings, we suffer early on release day and we drink that evening with the rest of the team. Think of it as dev-doc. This approach has a lot of useful advantages. First of all, I can come to an understanding of the software from the perspective of its developers. I know the user stories that informed the design and the why and how of the solutions that were used to build software that will give those stories happy endings. Furthermore, being involved with the team during development means my writing tasks are not limited to manuals. I can actually contribute to the software itself: UI strings, error messages, help text, tool-tips, etc. This can directly improve the user experience (I’m not saying our devs can’t write, but it sure helps to have a dedicated wordsmith). Part of being embedded means that I also serve as the team librarian, which means I am the curator of a whole collection of docs. This is real curation, as opposed to the Portlandia sense of I have a collection of pickles or vintage bike tires. Rather, I need to be an on-the-ball reference librarian and consider the needs of:
current devs on the team (what facts do they need to get their hands on to do that voodoo that they do so well)
current devs elsewhere in the company who need to understand how something was built was by my team
future devs who will come on-board and need to see the big picture architecture of the product plus implementation details in order to get up to speed.