Comparative Reality

For 13 1/2 years now, I've been employed as a technical writer. By half a dozen companies (and one consulting job), and writing damn near every type of software doc possible. But in my current position, "technical writer" doesn't cover my role or responsibilities.

It's only taken me about 3 years to figure out what I'm actually doing.

(Warning! Long, rambling post ahead!)

...

I was hired as a tech writer, and given the job of cleaning up and adding to the online, internal documentation. Which is on a wiki, but, hey, I figured I'd be documenting tools, API, writing some tutorials, etc., so no problem. And that's sort of been true for a while. But I've been limiting myself, and my role.

Now, for quite a while I've realized that I need to do more: You can't just add to a wiki haphazardly if you want something that's even remotely useful. So I've been trying to organize topics by user role, and flailing around with some sitemaps to help users figure out where the hell to find stuff. But the more I tried to do, the more I could see the gaps in my knowledge. So for quite a while I kept my head down as much as possible, and concentrated on what I call "doc triage": Get as much documentation done as quickly as possible. A fair amount of breadth, but very little depth.

I discussed the issue of usability, especially regarding finding all of this information that I had pried lose, but all I could determine was that the solution was not at all obvious, and probably not easy to implement. What I really hate, though, is admitting that something relating to documentation is outside my area of expertise. I'm a technical writer, after all! I deal with documentation 40 hours a week (if I'm lucky), and I've been doing so for years. How can this possibly be something that I can't solve?

But these problems have been gnawing at me for a while. I know things are broken, I don't know how to fix them, and that fuels the old, familiar concern: One day, my bosses will realize that I don't have a good answer, and so what the hell are they paying me for?

Two things have helped this: One, I was able to hire a very smart junior writer to help with the mountain of doc requests. Not only is she a good writer, but she's not afraid to test the various features of the wiki to come up with some new doc layouts. Some don't work, but others do, and that makes the experimentation worthwhile.

But then, why didn't I try that? For one, I've been head down, writing docs as quickly as possible, as I said before. But I realized that I've been limiting myself to what I was taught when I was a wee tech writer: How to write for print/PDF and online help. A wiki is neither of those things. It's online, but it doesn't work as well as online help when the topics are separated into small chunks. But it also doesn't work if you try to write chapter-length topics. Plus, there are plug-ins and add-ons that can be used to create different types of tables, better code formatting, collapsible text areas, and that let you grab content from one file and use it in multiple places. That one, I use all the time: Single-sourcing is the goddamn Holy Grail for tech writers.

And it's dawned on me that there's more out there: I read The Design of Everyday Things a few years ago, and it changed the way I think about all sorts of design, from physical objects to software user interfaces. It's not that the book says "This is the way to design things properly!"; instead, it gave me the vocabulary to use to describe poor design decisions when I see them. Which, in turn, gave me more confidence to express my opinions about the subject.

So the concepts of good design, bad design, and how to demonstrate which is which have been with me for a little while. And it's been obvious that I needed to come up with a good way to help people use the wiki docs; hell, just to be able to locate the docs buried in the site.

In the interest of improving the documentation, I pulled out some books that I've had for years, but only skimmed. First was Illustrating Computer Documentation. I pulled some good ideas out of this; some were implemented immediately, and others went onto the Future Improvements list.

Staying with the theme of graphics, I read The Visual Display of Quantitative Information. This one was less immediately useful to my career, but it's one of those books, like How to Lie With Statistics, where you're better off for having read it. They're not only well written, but they contain information and examples that are immensely useful to anyone who enjoys thinking critically.

From there, I spent a small fortune on books that seemed more directly related to my immediate knowledge management problems. I picked up Don't Make Me Think, a book about web usability. I thought at first that it might be too simple, and not very useful to someone with as much experience as I have. Fortunately, I was wrong. The unfortunate part is that I realized how unusable the current wiki layout is, and I started to feel daunted, again, when thinking about what needs to be fixed. Which is not to say anything against the book: I doubt that I could have picked a better place to start. I felt that I was starting to understand more about the problem, and that it was, in fact, a hugely common problem. It wasn't just me dealing with what I assumed was my own limited expertise: Everyone who designs a web site has to deal with this!

From there...well, that's enough for the moment. Another long, rambling post will follow shortly.