| Authors: | Heidi Waterhouse |
|---|---|
| Time: | 12:00 |
| Session: | http://docs.writethedocs.org/en/2013/conference/talks.html#heidi-waterhouse |
| Link: |
On January 2, Framemaker 10 had a wide-spread date-based failure, which impacted Waterhouse. She spent the better part of three days trying to figure out how to fix the problem, and in the end she was coming to Adobe angry. And our users probably come to us angry because they can’t find what they need in the documentation.
When Waterhouse began doing technical writing, they were building “TOC Documents”. These were orderly, linear, and searchable, but this approach also was rigid and linear, and left users out of the process.
Task based documents were more thoughtful about users and more modular. They’re modular, so they’re easy to single source. But they wind up being too “chunky”, hard to discover, and very rigid about the information. They’re also usually poorly indexed: the title is natural language, but the content often gets overlooked in the process.
Lately Waterhouse has been seeing “Guerilla Documentation”: documentation that the users create for themselves because they’re fed up with the “real” documentation. Today there’s some semi-official guerilla documentation: user forums run by software companies, etc. Because it’s user created, it’s relevant to actual user needs. Unfortunately it can become stale quickly, and it’s uncontrolled so it may be harmful (ie, an Android patch on XDA). Users have to leave your ecosystem to find the information, and the signal to noise ratio is very low.
So what if we took the best of all three approaches, to develop something Waterhouse calls “Search First Documentation”. It’s responsive to user needs, self-triaging, born searchable, and made for cross-referencing. Tags and keywords, in their best forms, tell you what users call things: “blue screen of death” doesn’t show up in Microsoft’s source or manual, but we know what that is.
So how do you do that? You gather data about what people are looking for from tech support, user communication, and even your inbound search log. If you triage based on a normal distribution, you’ll find the most important things to begin writing documentation on. And publish all the time.