Technical Writing: Not Sexy
I cannot even begin to tell you how many times I’ve seen peoples’ eyes glaze over with boredom when I’ve been asked to describe what I do for a living. Usually the response is, “Uh hah. Interesting…” and then they wander away. Far far away. “Come back! I’ll talk about sports with you!” I want to say, but I don’t, because I don’t like most people, nor do I really ever want to talk about sports (unless the Texas Rangers are in the World Series).
What I do is not sexy, but it can look a lot of different ways depending on where you work, what industry you’re working in, and the needs of the institution in question.
So, what is technical writing anyway?
It’s just business writing. Technical writing is grammar nerds red pen-ing all over things that SMEs have already written. It’s taking technical subject matter, and dumbing it down so your grandma could read and understand it. It’s identifying those holes where there’s a lack of content and working to get content created where there once was none. It’s being clear and concise. It’s remembering to coin acronyms (when you’re not blogging your little heart out). It is an intense H A T R E D of Microsoft Word.
It’s taking documentation and making it better.
In my experience, technical writers do a few things really well.
- Organization — Got a cluster in your wiki or website? No prob. We gotchu. Need the information in your document to flow better? Technical writers are hyper OCD folk with an eye for detail and the capacity to put up with tedium. Use us! We don’t bite (much)!
- Problem Solving — At a very fundamental level, all technical writing seeks to solve a problem. Can the people reading your product guide understand what it says? No? Don’t worry, we tech writers will ask the dumb questions so your readers don’t have to! Have brain drain from attrition? NEVER FEAR! Your friendly tech writer will get that content out of peoples’ heads and into whatever CMS you use!
- Understanding the Audience — No one (I repeat: NO ONE) wants to pleasure-read technical documentation. They’re reading it because they’re looking for specific information they have yet to find on Google. I’m of the opinion that giving readers the information they’re looking for, as quickly as possible, with as little headache as possible is an actual art form.
Okay, but how does it look in practice?
I’ve done technical writing at a bunch of different places, for a bunch of different industries. I’ve worked for a major IaaS provider (in the cloud), I’ve worked with electrical engineers for a semiconductor fabricator, I’ve worked at smaller companies in the FinTech, Regular Tech (I call it Tek Tek), and SEM industries. You name it, I’ve probably worked in it.
What can I say? I get bored easily.
Along with working as a technical writer in many different industries, I’ve also used many different tools, content management systems, and editors. I’ve had different job expectations. I’ve done technical writing for internal teams, and external customer bases. I’ve been “owned” by (read: the budget to pay me comes out of) marketing departments, product departments, development departments, and operations departments. I’ve worked for fully-formed long-standing technical writing departments, and I’ve blazed my own trail to create a completely new technical writing department. I’ve been organized under a central manager, and I’ve been embedded with teams. I have eaten MANY different flavors of corporate birthday cake, my friends, M-A-N-Y. (If any Office Managers are reading this, stop buying the Costco cakes please, they’re terrible.)
Technical writing can look a bunch of different ways, and there is no one right way, but there are ways I like and ways that suck really really badly. I will go into the differences in a later post, but suffice it to say, you should probably not implement technical writing in a way that sucks really really badly.
I have formed opinions, and that’s dangerous for everyone.
“You do not really understand something unless you can explain it to your grandmother” — Unknown (Maybe Einstein???)
There are some things I’ve done in my career as a technical writer that have shaped my philosophy. If everyone groked the manual, my job would be easy, but they don’t and here we are. To be a good technical writer you have to be part mind-reader, listener, translator, writer, editor, and at least passably adept at SEO, XML, HTML, and CSS.
To be a kickass technical writer, you have to be able to understand complex things and translate it in such a way that your 89 year-old grandma with hip dysplasia and hearing aids who starts every sentence with “Well back in my day, we didn’t have…” will pick up what you’re throwing down.
As a kickass tech writer meself, here is what I’ve learned:
- Read and listen. In order to write well about something, you must first understand it yourself. If I could give young tech writer babies one bit of advice, it would be to take the time to research the subject, or to just have conversations with people that know a lot about whatever thing you’re trying to learn. I always tell people I’m an eternal student. Your goal as a tech writer should be to become an SME through osmosis.
- Explain things thoughtfully. Most technical writers will tell you they simplify complex systems and processes. They bring order to chaos. They reign in the madness that is the technological landscape. And while that is true, it starts by explaining the crap out of things, then you edit, edit, edit, remove, remove, remove! As Carl Sagan once said, “If you want to make an apple pie from scratch, first you must create the universe.” Start explaining at the beginning and go from there. Even if you wind up over-explaining something, people will still just skip to the part they’re most interested in anyway, and if you under-explain something people will bitch until you over-explain it, so you should air on the side of over-explaining. You can’t make things better if you haven’t found the (hor)crux of the problem, and you can’t get there if that part has been left out.
- Make information easy to find. Along with grammatical nonsense that will annoy even the closest of your friends and family, your bag of tricks as a tech writer should include ensuring that information is easy to find. Whether this takes the form of reordering navigation trees, making documentation more searchable, adding a table of contents hither and thither, or simply divining what your audience wants to read and then writing down that thing first, you go do it sister. Always bear in mind that you can’t change human behavior. People skim, they don’t read. You’re not even reading this right now, are you? You look beautiful today and you bring sunshine and love to everyone you know. See? You missed a compliment.
- Write for the people who will read it. This may seem like it runs counter to my previous bullet about over-explaining, but’s a balancing act to write for the people who will read the docs, and to automagically know what information is necessary and what is superfluous. That shit takes time to be good at, but it always starts by asking the question: Who is my audience? Remember: users are going to experience documentation differently than creators. You should consider that in your writing.
- Fix problems, don’t create more. It’s easy to get carried away making things look the way you want them to look and writing docs the way you want to write them. If the way you’re doing documentation doesn’t suit the people that will be reading it, ya dun fucked up already. Technical documentation should solve problems. It should contain the answers the users seek, and if it doesn’t, fix that shit. Technical writers should be flexible enough to understand that in this day and age, documentation is malleable. It can change. We’re not writing things in stone here. We’re forever versioning.
In conclusion: Technical writers are cool, and I’ll be writing about that now because I cannot keep reading the news and thinking about what POTUS is up to. It’s unhealthy.
Welp. This has been fun, but I’m tired and cranky now… and I need tacos. Until next time.
