Write the Docs: Heidi Waterhouse — Search-first documentation: tags and keywords for frustrated users

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 wrapped up talks just before lunch. She talked about search-first doc­u­men­ta­tion and how search-first writ­ing serves users. As she put it, lots of our users are com­ing to doc­u­men­ta­tion angry. They have prob­lems they need solved and can’t find the answers.

Heidi started in the mid-90s with table of con­tents focused doc­u­ments. These are won­der­ful in that they’re orderly, lin­ear, search­able, and often indexed. But, they are also rigid, lin­ear, over-described, and leave users out of the process. They ignore the fact that a good doc­u­ment doesn’t just include every­thing in the world.

Mid-career she moved on to task-based doc­u­ments. These are great in how they take in to account the goals of users. While they’re more mod­u­lar they can be too chunky and hard to dis­cover. There’s no path through these doc­u­ments. You can hop from one task to another but the over­all pic­ture and flow becomes dif­fi­cult. Task-based doc­u­ments are also rigid about the infor­ma­tion type they require.

More recently Heidi’s seen guer­rilla doc­u­men­ta­tion appear­ing. This is largely user-created, rel­e­vant to real needs, and may sur­prise you. The down­side is that the doc­u­ments can get stale, they’re uncon­trolled, and they require leav­ing the ecosys­tem of the prod­uct. The sig­nal to noise ratio can also be hard to determine.

Heidi’s pro­posal is that we take the best aspects of each of these mod­els and cre­ate a new model. The model of search-first doc­u­men­ta­tion. We’ll end up with some­thing respon­sive to user needs. It will be doc­u­men­ta­tion that is self-triaging and is born search­able. Ideally the terms used in this type of doc­u­men­ta­tion comes from your users. It’s not impor­tant what you call a fea­ture, it’s impor­tant what users call it and how they’ll search for it. For exam­ple, “blue screen of death” appears nowhere in Microsoft’s doc­u­men­ta­tion but we all know what it means.

To make this type of doc­u­men­ta­tion hap­pen you first need to gather data. Using tech sup­port, user com­mu­ni­ties, and Stack Overflow you can get all the info you need. Second, you’ll have to write the docs and keep pub­lish­ing all the time. Writing pithy docs will help you focus on respond­ing to a spe­cific ques­tion. Plenty of these ques­tions won’t be answered by a sim­ple task.