OK, let’s get this thing out of the way. I’m a technical writer and I have been reading a lot lately about the challenges of technical writing. How original, I know. Bear with me here.
We’ve recently had new additions to our group. So, in order to give the newbies some words of encouragement and arcane wisdom, I tried to channel my inner grandpa and initially decided to convey my own insights and ruminations about the craft: I would pepper my speech with a bunch of (slightly) hyperbolic but totally plausible anecdotes to imbue them with a feeling of respect and reverence and fill their tender hearts and minds with a sense of awe. I would inspire this new batch of technical writers. I would inspire the hell out of them, so help me God.
I made a checklist and everything, look:
- Hear what my new colleagues have to say, ask them to share their experiences.
- Confront them with greatness: expand their awareness of what is possible in technical writing.
- Instill them with confidence and a fierce feeling of purpose.
- Remind them that they should not be afraid to ask for help.
- Show them they can be (or convincingly feign being) unapologetic and unabashed about their language prowess.
- Mention in passing that Amy Tan and Kurt Vonnegut were technical writers once, probably. I think.
- Check whether Kurt Vonnegut and Amy Tan were, in fact, technical writers.
- Use words and phrases that will make me sound smarter, like: ‘imbue’, ‘hyperbolic’, ‘the craft’, ‘tiger’, ‘traipse’, ‘fiery’, and so on.
- Make the case that no one explicitly denies that technical writing may have saved the world from fiery destruction at least once.
The list went on and on, but at some point I realized I was in way, way over my head here. My beard is not that grandfatherly. I don’t have a booming voice. I was denied the approval to carry out the training meeting in candlelight to set the right mood because of ‘fire hazard’. And maybe I should read some more about the challenges of technical writing just to make sure my speech is awesome and mind-blowing but also accurate and comprehensive. I was also told to ‘keep it brief and please don’t blather on about tigers again.’
But tigers are awesome! Retractable claws, stripes; I’m telling you: if more technical writers were tigers, things would get pretty interesting real soon.
Anyways, I read a gazillion blogs and papers and essays, and watched several videos about the challenges of technical writing, and all of them agree: most experts in almost all fields of human knowledge are not particularly interested in technical writing or especially aware of it.
I dare say this is the main challenge of technical writing. Seriously, I think I’m onto something here.
And it’s a shame: some of these people know weird and complex things, crazy stuff all over the place and no one cares too much about jotting it down and maybe putting an index and throwing in a table of contents in there (if they’re feeling fancy), and maybe do it so everyone can understand it easily.
But that’s fine, you know. Because I am interested. Leave it to me. Leave it to technical writers. We’ll deal with it. What now? You built this great tool and you know all that unbelievably complicated mumbo jumbo and you also have to be able to convey it in a straightforward fashion? No way. I mean, bravo if you can. Otherwise, just call a technical writer, we’ll technically write it for all to see. No problem.
Seriously, we’ll do it. We may even enjoy it. Why, it’s not unheard of. We are just going to need a few things.
Your Friendly Neighborhood, the Technical Writing Team
No technical writing department is an island. I work in IT, and have worked for IT companies long enough to know we cannot function in a vacuum. We try. Trust me. We try really, really hard to finish all those handbooks and manuals and installation guides without help. We know you engineers and developers and testers are busy, busy, busy. We pore over what disparate data we may gather. We skim and scan functional specifications, statements of work, detail engineering design documents, contracts, old e-mails, tea leaves, messages written on toilet doors, weirdly shaped clouds; everything and anything we think may help us avoid having to disturb you.
We’ll do almost anything, really. We’ll reverse engineer the demo (pretty please, with sugar on top, give us a demo to work with), we will even try to install and later uninstall programs called esoteric names like ‘Technobabble’ or odd acronyms like ‘WTF-9’.
I know technical writers look weird and talk a lot about nerdy stuff and make a lot of annoying puns, but we really need the interaction. We are just different types of nerds! Talk to us, we need information, and that information is spread around in dozens of pseudo-documents, post-it notes, napkins, written on whiteboards and scrawled on the palms of many hands.
And in you. Yes, it’s also in you, you beautiful and elusive subject-matter expert.
We are going to approach you. And we are going to ask you some questions. We are probably not experts in the matter at hand, so you are going to have to be patient and tell us what we need to know loudly and clearly.
We are going to have to explain it to the end users, see? The very same end users that are going to completely misuse and wreck your precious tool or application if we were to leave them to their own devices. Human beings are extraordinary creatures and they really push the boundaries when it comes to clicking buttons the wrong way and entering data just the right way so even the most redundant system crashes and teaches us a lesson about hubris.
Please, subject-matter expert, remember this mantra: if it’s not in the documentation, it’s a bug. If it is in the manual, it’s a feature*.
If you won’t do it for that, think about the technical support engineers or the professional services people, they will be so happy! To have a manual available to help them find configuration issues or workarounds? Priceless!
I promise we have read a lot about the subject, we are informed; we try to keep abreast of the latest developments. It is us, your friendly neighborhood, technical writers! We are going to need your help. You know the thing, we know the writing. We are going to make a great team.
I would also like to ask my fellow technical writers: what else did you expect? And I don’t mean it in a flippant way either. Not many people have the time or the mind-set to get involved in the work of others. Everyone is trying to do their best under very trying circumstances. A lot of companies in the IT sector are striving to be ‘flexible’ or ‘agile’, this generally means roadmaps can change any minute and deadlines get increasingly short, which will ultimately cause a chain reaction that will unravel the very fabric of the space-time continuum and destroy the entire universe, probably. Ok, maybe just the Virgo Supercluster.
However, I’ve found out that, under certain circumstances, experts will share their knowledge; they might even want to share it. I mean, they’ve just solved a problem, they had to use their wits and cunning to do something that had never been done before; at least not exactly this way, with so few resources and in such a short time. Wouldn’t you like to talk about your achievements? I haven’t even finished this article yet and I am already bragging about it (dons beret).
I guess it’s a matter of tenacity, timing and a bit of luck: TTAABOL (it grows on you, say it a couple of times or 500). It shouldn’t be this hard, I know: there should be a process that everyone abides by, and this awesome process should take into account the time, effort and resources needed to successfully document updates, new features and changes to existing products. All project schedules should include documentation milestones. It would be so nice. Project managers would know that documents need to be reviewed once we have delivered them but before they are published, and they would plan accordingly.
It can be done, but you are probably going to have to train them, my technical-writing friend. Do not despair: directors and managers have proven time and again that they can be trained (or conditioned, in extreme cases). You need to be firm, and don’t show them you are afraid. Do not feed them unless they explicitly ask you to.
Be clear and concise and they will respond in kind.
In a company I used to work at, a recently hired manager once wrote the entire technical documentation of a product himself: user guides, deployment guides, installation guides, the whole shebang, because no one bothered to tell him there was a documentation department (me, basically) in charge of doing exactly that. It seemed I was hiding in plain sight.
Clearly, I had to do something. It finally dawned on me I was virtually invisible. So I did everything in my power (and slightly beyond it) to become the go-to guy when it came to writing. I would be the embodiment of writing, any kind of writing, within the company.
I started to infiltrate myself in everything that had to do with writing. I sent completely unrequested reviews (and rewritings) of contracts, marketing material, spreadsheets, SOWs, e-mails. Anything written I could get my hands on. It probably was a bit rude and intrusive but it worked: suddenly everyone was sending me their drafts, asking me to turn them into a professional-level piece of work. I wrote contracts, requests to providers, replies to customers, love letters, lyrics, a short story about two lovers who are time travelers, you name it. Then I had to narrow it down to just technical writing, of course, but it had worked. When my coworkers saw me, they tried to remember if they had anything for me to write. Eventually, people were telling me things.
I had established a channel.
*I didn’t make up that phrase… someone told it to me and it stuck, and I can’t find it on Google. Oh well, thank you, my forgotten (but not unappreciated) benefactor.
Sebastián Baroni
I am a Literary, Technical and Scientific English-Spanish Translator and have over 10 years of experience as a Technical Writer in the telecommunications industry. You can contact me at sebastian.baroni@intraway.com
