I’ve spent a large chunk of time this week building a case for hiring a technical support person. This has been a difficult, time-consuming process, and I’ve been thinking about how I’ve done this sort of thing before, and why it’s difficult now.
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.
I’ve been over-analyzing the process I use for content creation. In fact, it’s pretty simple, and the requirements are low. I don’t require a lot of technical overhead to create documentation for my company, and that includes written content, videos, screenshots, and diagrams. And tags and links and comments and a bit of organization.
I’m not creating a set of manuals, or building in-product help. (Not yet, anyway.) Which is what the majority of tech writers do, and I think that’s why I don’t get a lot of value out of most tech writing organizations and conferences.
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.
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.”
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.
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.
In my previous post, I described how I structure release notes, and what sort of content I include in them. This time, I’m going to focus on gathering information, when to release the release notes, and how to let your users know that they exist.