How to Build a House

We get a lot of feedback saying that customers want cookbooks. They want documentation that tells them how to solve a problem. They are not complaining that the documentation doesn't cover all of the features they need to use. They are complaining because they don't know which features to use and how to use them to solve the problem. How to address this feedback? Write cookbooks? For a typically resource starved doc team that would mean sacrificing feature documentation. Product managers generally frown on that. Besides cookbooks tend to have too narrow a focus for a general audience. Ignore the feedback and hold on to the belief that it is only a vocal few who aren't satisfied with the feature documentation? That won't stop the complaints. It also doesn't address the problem of users not knowing what to use when. It doesn't help users know how to use the product in a real sense. You could reframe how you approach the task of documenting the product. Instead of starting from "how do I use feature x?" can we start from "how do I solve problem y with feature x?"? I think you get documentation that satisfies both the users who want to know how to solve problems and the product managers who want the features documented. This approach is not easy. The difficulties start with the list of things we are given to write about. Typically the product manager hands out a list of features with little explanation of what problem they address for the users. I've seen lists that say things like "support WS-Security" with no statement of why that is useful. The writer needs to drag the use case for the feature out of the product manager if they know it. The writer has to also know enough about the product domain to have a general sense of what problems users are trying to solve. Once we figure out what people want or need to do with our products, documenting the features as part of building a solution should provide comprehensive coverage. There will still be bots that describe how to use an individual feature and there will still be reference material. It will just be organized around the idea of building a solution instead of using a toolkit. One question I was asked was about "less popular" features. My answer was that if a feature is used to solve a customer's problem it will get covered. If it doesn't solve a problem then maybe product management should consider yanking it.

Bit Literacy by Mark Hurst

I downloaded this book from Apple because it sounded interesting and it was free. It is not the sort of book I would pay money to read. The description made it clear that this was a book with something to sell.
Bit literacy is the product and Hurst's company will gladly sell it to your company for a hefty fee. I don't begrudge Hurst for this or think any less of him, but I don't ever feel like paying for a marketing tool.
It turns out that the book has some good stuff in it. It also doesn't shy away from offering up details on using the system. So, if you are buried under bits(e-mail, photos, power points, etc) it may be worth paying a few
bucks.
The key to the whole system is rooted in standard productivity lore. Let the unimportant stuff vanish so you can focus on getting things done. Don't keep ten pictures of the same thing; only keep the best one. Don't save every scrap of e-mail because it buries the stuff you need to save.
Hurst is a proponent of inbox zero. You should empty your inbox at least once a day. E-mails are either junk to be discarded, to do items that need to be tracked, or information to b stored in an appropriate place. The inbox is not a place to keep to do items or information.
One other discussion I found interesting was the discussion of file formats for textual data. Hurst comes right out and says that Word, and its ilk, are never the proper choice for sharing text. He prefers plain text unless you require formatting. If formatting is required he prefers PDF.
Bit Literacy has some interesting ideas for writers as well. Hurst has a whole section on how to write in a bit literate manner. Basically it is all about front loading the point and brevity. Write in a way that respects that the reader is busy. This is not about pleasure it is about efficiency.
Hurst's book has some worthwhile points. There is something in there for anyone who uses a computer.