Ratings, comments, and collaboration

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.

Continue reading “Ratings, comments, and collaboration”

Question your assumptions

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.

Continue reading “Question your assumptions”

Overcoming the tyranny of the blank page

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.

Continue reading “Overcoming the tyranny of the blank page”