A requirement for any documentation that I create is that readers can rate and comment on the docs. I’ve been publishing documentation to systems that support this for about 10 years now, with a short gap in there. Not every tech writer agrees that these are necessary, or even desirable, so I’d like to analyze my reasons for being so stubborn about it.
I’m the documentation and support team for my company (startup!), which means that I get an interesting, and often valuable, view into the problems our customers are having. Most of them are technical (port numbers), some turn into feature requests, and some are questions about using the product. Those are often tricky, or subtle, and they’re particularly useful to me because they show me where the documentation could use some improvement.
And sometimes the user is having a problem because I screwed up. Let me tell you a story about one of those.
I realized that since I keep encouraging writing groups to collaborate with other teams, I should provide some advice. It’s one thing to say “Go do this!” But that does require work, and the least I can do is give you advice that’s helped me.
So here’s one: Don’t present your would-be collaborators with a blank page. If you’re a writer, or if you’ve written anything, ever, you know how daunting a blank page can be. For someone who doesn’t write that often, it’s even worse.