Published on 20 May 2013 by

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 Engineers

Undoubtedly, 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.

Based on all of that, I build and maintain a collection of documents. If I see holes, I try to fill them, either myself or by working with a dev. Knowing my way around this collection gives me vital context into how the software was built and why. Being embedded also means that I can more easily get devs to weigh in themselves on what they think needs documenting. I maintain a “pre-docs” repo which serves as a bucket where changes, features, and functions can be quickly noted and logged. No one but the team ever sees this repo, so devs can just jot stuff down without worrying about creating polished prose. If something doesn’t make sense, it’s easy enough for me to ask for clarification. I usually don’t even need to stand up, I can just throw wadded-up Post-Its at the dev in question until they turn around.

Building a Wider Documentation Perspective

All of these things inform how I create end-user docs. Not entirely in the sense that I can simply repurpose these internal docs, add some adjectives and expand the acronyms, and send ‘em out into the wild. Rather, all this internal documentation work informs my external documents in a way similar to how all the reading you did for, say, your American Lit class, ends up informing your senior thesis on Continental Philosophy. You internalize the perspectives, the problems and the paradigms, even if you don’t mention them literally. When I go to write user-facing documentation, my work on internal docs helps me with several things: information architecture and taxonomy, knowing what to emphasize and what I can leave out or just briefly note, and knowing how technical my docs need to be for my audience. All of this adds up to docs that are truly a team effort and that are closely tied to the product they document. Embedded writers means that docs at Puppet Labs are not an afterthought. Rather, docs at Puppet Labs are seen as part of the product and the user experience, and so everyone has a role to play in their creation. And this brings me to a closing call for action. If you, dear user, have any feedback, suggestions, revisions or contributions for Puppet documentation, we want to know. You can contribute directly or send us a note at docs@puppetlabs.com. In fact, if you really want to help out with docs a lot, we’re currently hiring a writer. Come join our dev-docs team!
Share via:
Posted in:

Add new comment

The content of this field is kept private and will not be shown publicly.

Restricted HTML

  • Allowed HTML tags: <a href hreflang> <em> <strong> <cite> <blockquote cite> <code> <ul type> <ol start type> <li> <dl> <dt> <dd> <h2 id> <h3 id> <h4 id> <h5 id> <h6 id>
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.