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”

What we write (and why I need to create more videos)

One topic keeps coming up in discussions about technical writing, and which bounces around in my head: What type of user docs should we create? The standard triumvirate is Conceptual, Procedural, Reference. But I’ve written that content as separate topics, as topics that contain two of the three, and even as topics that contain all three.

I have to warn you that I don’t have a definite answer. I doubt that one exists, but I believe that by addressing it, I’m improving the docs that I’m writing, and maybe getting closer to a solution. Although I suspect that the answer is a frustrating “It depends!”

Continue reading “What we write (and why I need to create more videos)”

Tech writers: The bard class of the corporate world

In D&D and related role-playing games (Dungeons and Dragons, and yes, I’m going full geek), the Bard character class gains a ton of skills: They’re a bit fighter, a bit thief (or rogue, if you prefer), and also have a bit of magical ability.

The point is: They’re flexible. They’ll never hit as hard as a fighter, aren’t as sneaky as a thief, and won’t cast as many spells as a wizard. But because they don’t specialize, they’re useful in many situations, and they’re often an asset to adventuring parties.

Lots of skills, very versatile, an asset to their team…just like technical writers!

Ok, I sense your doubt. Let me explain.

Continue reading “Tech writers: The bard class of the corporate world”

Using humor in your documentation. Or not.

Tom Johnson wrote a great post about user manuals, and wondered whether a bit of humor would help keep a reader’s attention, and make them more willing to read (and follow) help instructions. I have complex feelings about that, and I’ve been able to argue myself into agreeing and disagreeing with the use of humor in help documentation.

Is the possible benefit of adding humor to documentation worth the cost?

Continue reading “Using humor in your documentation. Or not.”