Technical Writing

I’ve been a technical writer in software companies for a long long time. This is my attempt to explain what I do and make it exciting! I’m in the job market right now, so this is a necessary blog post (for the portfolio and all).

Here is my take on what technical writers do: we simplify complicated concepts so people can understand them.

Technical writers:

  • Use simple language. Occasionally I use big words, if they are just right. But mostly I use simpler words that more people will understand. This will probably always be my writing style. I think this habit developed when I was young and started learning words that other people didn’t know. It was easier just not to use them, trust me.
  • Are allergic to jargon. Acronyms and arcane technical terms set off my antennae. If I don’t know what something means, chances are the average user won’t. (In the tech world, “users” are the people who actually use the software after it’s bought. If they need to read manuals or use help, chances are they won’t know the latest jargon.)
  • Are logical and a bit OCD. I have a different way of thinking than engineers, because I need to make lateral leaps to condense information. I’m fond of trying to find metaphors and running with them until they don’t work anymore, which is very annoying to some literalists. But, I do need logic to ask the right questions so I can explain things step by step. I like using numbered lists to do this, and making sure topics follow along rationally. I like to order information just so (that’s where the OCD part comes in).
  • Ask, “What would a person do with that?” and other “dumb” questions everybody is afraid to ask. People writing software often work in a small area of the code, so may not have time to think about the big picture or “the user experience” (how users actually use the software in real life). Sometimes there are team members who can explain everything to me (Yay! Love them!) But sometimes everyone on the team is stumped and I need to avoid explanations entirely. I’m not proud when that happens, but it’s not literature I’m writing and there are deadlines.
  • Are sometimes the canaries in the coal mine. If everyone has worked on their little piece of the project and nobody has tried to put it all together logically until the writer comes along, my job is sometimes to say “This isn’t making sense.” Occasionally I uncover a flaw nobody thought of. Sometimes I have to squawk about how I just don’t understand it at all. Luckily not often.

Fun fact! In French, technical writers are called “vulgarisateurs” or “redacteurs.” I’d like to be called a redactive vulgarizer, it kinda makes me feel badass.

Technical writers, like many others in the software industry, can suffer from burnout. It is really easy to start feeling defensive, especially if you’re the only one asking the dumb questions every day and people are too stressed to answer them. As well, we have to accept that our thousand-page magnum opuses (aka manuals) will be stale within a couple of years because technology changes so quickly. With the Internet, I guess we are no longer alone in this. Words have become a giant data storage experiment, and should all have a best-before date given the rapid change we all are going through. (They are stored “forever” though—that is a topic for another post.)

I’m up for being a cheerleader though. In the current age, I’m excited to be engaged in finding clear explanations, with a dash of vulgarization thrown in to get at the big picture. I have come to realize that words create change. If you explain something well enough for people to grasp a new idea, it means that idea can take flight. “What would I do with that?” is a question that has been asked throughout the ages, probably starting with someone wondering why someone else was rubbing two sticks together. The answers to that fundamental question have driven human innovation to astonishing levels.

Thanks for reading to the end. 🙂