I’m at Write the Docs today in Portland and will be posting notes from sessions throughout the day. These are all posted right after a talk finishes so they’re rough around the edges.
Heidi wrapped up talks just before lunch. She talked about search-first documentation and how search-first writing serves users. As she put it, lots of our users are coming to documentation angry. They have problems they need solved and can’t find the answers.
Heidi started in the mid-90s with table of contents focused documents. These are wonderful in that they’re orderly, linear, searchable, and often indexed. But, they are also rigid, linear, over-described, and leave users out of the process. They ignore the fact that a good document doesn’t just include everything in the world.
Mid-career she moved on to task-based documents. These are great in how they take in to account the goals of users. While they’re more modular they can be too chunky and hard to discover. There’s no path through these documents. You can hop from one task to another but the overall picture and flow becomes difficult. Task-based documents are also rigid about the information type they require.
More recently Heidi’s seen guerrilla documentation appearing. This is largely user-created, relevant to real needs, and may surprise you. The downside is that the documents can get stale, they’re uncontrolled, and they require leaving the ecosystem of the product. The signal to noise ratio can also be hard to determine.
Heidi’s proposal is that we take the best aspects of each of these models and create a new model. The model of search-first documentation. We’ll end up with something responsive to user needs. It will be documentation that is self-triaging and is born searchable. Ideally the terms used in this type of documentation comes from your users. It’s not important what you call a feature, it’s important what users call it and how they’ll search for it. For example, “blue screen of death” appears nowhere in Microsoft’s documentation but we all know what it means.
To make this type of documentation happen you first need to gather data. Using tech support, user communities, and Stack Overflow you can get all the info you need. Second, you’ll have to write the docs and keep publishing all the time. Writing pithy docs will help you focus on responding to a specific question. Plenty of these questions won’t be answered by a simple task.