My philosophy of technical writing

I said earlier on twitter that I like interviews because it gives me a chance to talk about my philosophy of technical writing and how I’d go about implementing it. Good friends reminded me that the ideal way to talk about one’s philosophy and implementation is while being paid a respectable hourly rate. That is very true! I have cut off interviews that I felt were exploitative.

The problem is that most business and development people don’t exactly understand what a normal technical writer does, much less a technical documentation architect with a heavy sideline in technical speaking. If I want to get a position that fits me, I have to explain to them why they need it. I don’t worry too much that I’m cannabilizing my own business because it’s so general that even my implementation details would be hard to implement without a grounding in the disciplines I used to construct them. Offering people a taste of my thinking is only going to whet their appetite.

Amazing pomegranate in the Tel Aviv market

Core principles

  • No one wants to be reading documentation.
  • Technology is a means to an end, not an end in itself.
  • Users experience technology differently than creators.
  • Answering questions is more valuable than comprehensive information.

Seems straightforward when I say it like that, right? But every one of those principles is something I learned the hard way, carved out for myself, watched in action. No one taught me that. Many people contributed to my thinking, but it is my synthesis that matters here.

Implementation

At the highest level, implementation is about interrogating why we write documentation at all. Could we solve it with better workflow? UI text? Detection? Scripts? Is there some way we can change the technology so that a user is not angry enough to go look up documentation?

If they are forced to look up documentation, how fast can we answer their question? We live in a world where you have been able to use natural language search for most of a decade. We need that to be true for documentation, too. “How do I configure this on Solaris?” “What’s the curl command for oAuth”? Don’t make people look for something, just…give it to them. This answer is deceptive. It sounds very simple, and implementation is a complicated blend of search, SEO, writing, and metadata. But not all beautiful things are easy.

If you can’t use something, you shouldn’t have to write about it. If you have to take the way software operates on faith, then are you really documenting it, or are you just transcribing the unverifiable claims of engineers? There are a lot of things that you can’t run, or can’t fully run, or can’t run in production, but there are lots and lots of things that you can hack through enough to test it and see whether the steps make any sense at all.

What do you call something you can’t use, can’t improve, and can’t answer questions about?

Vaporware.

A lot of my implementation philosophy comes down to not documenting vaporware. Vaporware is not the exclusive domain of hip new startups, it can happen anywhere, to the most established or productive of companies. I once started a job with a multi-billion dollar company, only to quit it 4 days later when I realized they were not clear on whether they were making an app or an API. That is not a scenario where documentation is going to help.

The projects I like best have the following features:

  • I can use it.
  • It solves a problem (I’m not great at documenting games)
  • It has very little existing documentation, so I’m starting fresh instead of retrofitting.
  • It has a deadline.

Those are personal preferences, and I almost never get all of them, but it’s nice to know what makes you happy.

Conclusion

I can tell you what I think about documentation at great length, and I can explain what makes good and bad documentation depending on who your audience is. Given enough time and consulting fees, I can tell you how to fix your documentation, or I can fix it for you, or I can create it new from first principles. My next set of goals is teaching developers to write more practical documentation, and figuring out how to teach other writers to work like this.

(Current goals: Give a keynote speech, get paid to teach a workshop)


This is cross-posted from my website, heidiwaterhouse.com