Fast. Good. Cheap?

I usually work in a tactical writing mode: documenting new features and workflows in an agile development environment, or writing special content for training or specific customer requirements. I’m very comfortable working at a tactical level. But in the iron triangle of fast/cheap/good (where you can pick any two), going for fast/good incurs a cost that’s very easy to miss for a while: losing sight of the strategic goals…or failing to create them at all.

Continue reading “Fast. Good. Cheap?”


A few ideas and one scandalous revelation

My last post was number 25 (sorry about missing a week). That means that I’ve been posting for 6 months (I missed a week). My goal is to reach 100 posts and then…well, I’m not sure. If my posts by then are “let’s look at the things on my desk and make them metaphors for technical writing,” then I’ll pack it in. But now that I’ve hit a round and arbitrary number, I’m going to write down some ideas and plans. And I’ll reveal Shocking News!

Continue reading “A few ideas and one scandalous revelation”

In search of the perfect (or perfectly adequate) writing tool

Everyone who uses tools for a living loves their tools. And has strong opinions about them. Most programmers are happy to talk about their favorite coding languages and development tools, for example. For tech writers, we get to argue about content management systems, authoring tools, authoring formats, documentation structure…And that’s after we’ve battled over grammar, font choice, and glossary terms. Seriously: Glossary battles are the worst.

Now I find myself needing to change my writing process, and probably adding a tool or two to my workflow. Oh joy.

Continue reading “In search of the perfect (or perfectly adequate) writing tool”

What did I expect to get from conferences?

I really like Tom Johnson’s recent interview with Pawel Kowaluk, who is organizing a techcomm conference in Poland. After a much appreciated compliment, he explains that he’s trying to include topics that show how techcomm is a vital component of a company’s business practices, and not an afterthought, a bolted-on requirement that gets included because it’s just how things are done.

Which is what I’ve been trying to get to, and why I keep wandering around the point of why I think techcomm is important. And also why I’ve been frustrated when conferences become advertisements for tools or specific processes, without really explaining how we make the business case for our existence.

Continue reading “What did I expect to get from conferences?”

What I’ve learned in a week (and a bit longer than that)

After the great response to my previous post, I should probably write another post about something else that tech writers are doing wrong. And although there is a part of me that would love to write a purely contrarian article for the hell of it (“Structured writing: Threat or menace?”), the responses to my post were so intelligent and reasonable that I need to focus on positive contributions.

Continue reading “What I’ve learned in a week (and a bit longer than that)”

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”