Write the Docs: Heidi Waterhouse – The New Sheriff in Town: Bringing Documentation Out of Chaos

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Heidi is a technical documentarian of about 20 years now. Her talk focused on bringing order to a chaotic environment. Her specialty is working with companies that have never had a technical documentarian before and helping them get a solid foundation in place.

Part of this involves trusting that you’re the starting point for these companies. If that company believed in documentation they already would have hired someone. Trust that you are the expert with the authority to bring that value and illustrate its impact.

The first thing you do is set up shop. Make a seating chart of the office so that you can remember where people sit and what their specialties are. Draw a map of the existing docs and how to get to them. It lets you know the neighborhood, competitors, and users. There’s always some conglomeration of poorly structured documents somewhere. Ensure you have access to them. Looking at competitor’s documentation gives you a sense of where your company stands. It lets you determine what environment your docs will be living within.

When writing documentation within a company, there’s no time for frills. You need to deliver early and deliver often. Or, you must talk about why you can’t deliver. You can get to precision between emergencies but you must ensure you’re dealing with emergencies first.

Draw your docs fast. No one can give you feedback if they can’t find and read your documentation. The early format matters far less than its delivered state.

The next thing you do is save the townspeople. If you can’t envision which person is being saved by that document then it’s likely not saving nor helping anyone. Address the biggest internal pain points and give them a structure to ask about things and give feedback. Those quick easy wins shows your value and quiets your internal feelings of being an imposter. In terms of giving feedback Heidi pushes all documentation changes through the same bug tracker and code process as the product. Documentation edits are created as bug tickets and assigned to her.

Then, you’ll want to check for scorpions. These are situations, not people. If you blame people you face an uphill climb; focusing on situations lets you solve things systematically. Look for hoarded documentation, carryovers from the last sheriff in town and then bring in the vigilantes. The vigilantes are those hoarding documentation; they care but are operating outside the bounds of the law. Rolling them in to the work you’re doing creates consistency without alienating previous doc owners.

The last thing you’ll do is build infrastructure. You should plat your documents and find gaps; consider the use, configuration, customization, reference, and necessary fixes for documentation. Your infrastructure for continued growth ensures that documentation is seen as a first-class citizen in the product and not a forgotten afterthought. Be the voice for docs at scrum meetings, architecture sessions, and more.

Documentation sheriffs are part of a town. You’re not a hired gun who rides in to town, shoots people, and leaves. True sheriffs build a community and long-term structure for the documentation they’re creating.