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”

Do our docs really need a Table of Contents?

I’ve long been a devotee of table of contents (TOCs) in documentation, both online and offline. This was the accepted best practice, and I rarely thought much about it. After all, TOCs allow the reader to skim and do an efficient visual search for the information that interests them.

But I wouldn’t be writing this if I didn’t have some concerns about automatically including TOCs. Is it really necessary? Do readers use them, do they ignore them, or do the TOCs actually annoy them?

I’ve found that the answer is a frustrating “All of the above.”

Continue reading “Do our docs really need a Table of Contents?”

2014 Resolutions

I don’t usually create resolutions for the new year. It just wasn’t a thing that I, or my family or friends, ever did. But I’m working on my annual goals for work, and it got me thinking about professional development, and what I can do about that in 2014.

I’ll try to create a list that’s fairly realistic, but I’m still going to organize these goals by the likelihood that I’ll actually get around to them.

Continue reading “2014 Resolutions”

Online vs. offline documentation

I’ve been thinking about documentation tools and publishing platforms. I’m evaluating what I have, and what more I need. To be less vague: I have an online knowledge base/help center. What I need, or might need, is a way to provide that content to users who aren’t online.

After setting up and writing content for wikis and other online-only systems for years, the concept of “offline documentation” seems obsolete, even primitive. But I have to admit that there are still some use cases for it, even if the letters P, D, and F make me shudder in fear.

Ok, that might be overstating it a little.

Continue reading “Online vs. offline documentation”

Everything I know about release notes. Part 1.

I’ve been writing release notes this week. This is a new thing for my company, so I get to decide what they include and what they look like. I’ve written release notes many times before, for different companies with different requirements and styles. I’ve filtered all of those styles into what I think of as a “general” style for release notes, which is my go-to style: short, uncluttered, let the reader get the info as quickly as possible.

But let’s see how that idea holds up once I start analyzing it.

Continue reading “Everything I know about release notes. Part 1.”

Docs and sales and changing roles

My role is changing again, but this time back towards tech writing and support. I’m moving away from customer success, and away from direct training; but to be honest, I hadn’t been doing much of either, so it really comes down to continuing to do what I’ve been doing. Although that will probably change, and expand, in the future.

Confusing? Yeah, to me, too, but it’s not at all bad. And I think it reflects something becoming more common for us content creators.

Continue reading “Docs and sales and changing roles”

Refining my ideas about videos

I’ve established (at least to myself) that I need to create more videos for my documentation. I’m still working on the details: length, content, and how I can convince other people to do the narration.

Even for short videos (which is what these will be), I know from experience that there’s a lot of editing involved. And I get sick of hearing my own voice very quickly.

So it’s Time to create some guidelines. And next month (or so) I’ll review them to see how well they corresponded to reality.

Continue reading “Refining my ideas about videos”