The New Sheriff in Town: Bringing Documentation Out of ChaosΒΆ
| Authors: | Heidi Waterhouse |
|---|---|
| Time: | 10:20 - 10:40 |
| Session: | http://docs.writethedocs.org/2014/na/talks/#heidi-waterhouse-the-new-sheriff-in-town-bringing-documentation-out-of-chaos |
| Link: |
Technical documentarian of almost 20 years, and here to talk about the chaotic environment and how to bring some order out of it. By the time people get to this point in their career, most people have specialized in something; she’s specialized in coming into organizations as their first documentarian.
So how does this work? Well first, you need a Star. And the only Star you’re going to get is that you got a job: you convinced a hiring manager that you could do the job, that you could handle their thorny problems. And no one is going to give you anything else. So you have to get over your imposter syndrome.
And then you set up shop. When you roll into town, people will show you around. But you probably won’t remember any of that, so make your own map/seating chart of people and documentation. So that when someone says, “Hey, Janet knows about SQL, ask here,” you’re able to approach Janet confidently. And there’s almost certainly existing documentation, no matter how ill maintained. And while you’re waiting on your laptop, provisioning, whatever, get to know the neighborhood: read the docs of your competition, of others in your domain. Understand the lay of the land.
Once you start writing, you have no time for frills. You need to draw fast. Polish and precision (formatting, localization, etc) will happen between emergencies. Deliver early, deliver often, or talk about why you can’t deliver. Early/often delivery helps demonstrate why this documentation thing is important. The polish and precision is important, but it doesn’t matter if you don’t put out the fire first.
And now you’re going to save the townspeople: find the biggest pain point you can address and take care of it. Maybe it’s just a PDF form that customer support doesn’t know is possible. It helps others, gets them on your side, and quiets your internal imposter syndrome. You also need to give others a way to ask questions and communicate with you. A bug tracker is a great way to handle this, and gives you a punch list to work down on days when writing feels like too much.
You’ll also often find scorpions: documentation hoarded in inaccessible tools, or a disorganized manner. The people who are hoarding are vigilantes: they care about documentation, but they’re operating outside the law, so you want to deputize them and bring them into the “official” documentation project.
Finally, it’s important to build infrastructure. Once the fires are out, it’s important to provide some structure for continued success. This means templates, release notes, etc; make sure that documentation is part of the process for new code, new features, etc. That ensures that it becomes part of the long term success of the organization.