What makes a technical writer tick?

24 Jun

Posted by Scott as career, documentation, general, opinion, skills, technical communication

tech-writer We’ve all seen those lists of characteristics that make a good technical writer, as posted in job ads or course descriptions. They’re more like a wish list than anything based on fact. I’d be a pretty weird person if such a list described the whole me. “The ability to turn geek-speak into baby talk; the ability to spot a mizplaced (sic) zed from ten yards out; unflappability when informed that the deadline that everyone else knew about has just passed; unquestioning acceptance of the ineffability of product management; flexibility to the point of contortionism; fluency in 42 languages, none of them human; preference given to Klingon …”

Come to think of it, technical writers are pretty weird individuals. And proud of it. You’d have to be, um, unusual, to actually enjoy writing. On 8 June this year, a United States district court judge sentenced a white-collar criminal to write a book. That’s right, the crim’s penalty is to spend a significant period of time writing.

What goes into the making of someone who does technical writing all day? Rumours are that we’re intensely interested in the exact placement of a semicolon. Well, that’s true of course. But there’s more.

Fact: Many technical writers report that chocolate plays a key role in their lives and careers.

Big and small

We enjoy and are skilled in document design, both micro and macro. By micro, I mean the design of a single document or page: structure, aesthetic appeal, content, usability, applicability to audience, and so on. By macro, I mean the design of a documentation system: this has many of the same requirements as the micro but is applied to the whole documentation set as a unit, and adds technical considerations like platform, medium and interoperability with other systems. There’s more, but you get my drift.

All sorts of people end up as technical writers. That’s part of what makes our field so rich and enjoyable. We have in common a love of and skill in language and the written word. Many of us have a flair for, or at least a working ability in, graphic design. Many have done system development. (I have developed in COBOL, Basic, VBA, JavaScript/CSS/HTML, LotusScript, Natural/Adabas and have played with C++ and Lisp.)

We are power users and administrators of content- and document management systems like SharePoint, Lotus Notes, Documentum, blah blah. We are power users and administrators of content creation, layout and publication tools like RoboHelp, Office, FrameMaker. We’re totally au fait with the web, HTML, CSS, yada yada. Many of us dabble in XML technologies and the alchemy of chocolate.

A key skill in technical writing is the ability to tailor your language to suit your purpose, audience and medium. This blog post is a working illustration. Good or bad? That’s debatable. Drop a comment on this page — You wouldn’t write a technical document in the style of this post. On the other hand, if this post were a list of stem sentences, how-to steps and bullet points, you’d have stopped reading at the first reusable chunk.

A key step in preparing a document is to discover the requirements of the people commissioning the document, be they the product manager, project manager or chief bottle washer. In the case of this blog post, there was a very clear requirement not to mention what idiots Aaron and Scott are, since they claim to do enough of that amongst themselves. So I won’t go there …

Do you have it in you?

If you are not a technical writer but have stumbled on this post somehow, here are a couple of things you may find useful.

First, here’s something you may not want to know:

If you’ve got this far, you have at least some technical writer in you. You may even be a closet technical writer …

Second, here are some places where technical writers hang out on the web. Come and join us:

The Content Wrangler Community on Ning.
TECHWR-L discussion list and web site.
A number of groups on LinkedIn, such as Agile Technical Writers, Software User Assistance, Technical Writers Australia, Writing Mafia and more.
Blogs like Communications from DMN (that’s this one), just write click, I’d Rather Be Writing, Shanghai Tech Writer, Clever Hamster and many more.
Facebook, Twitter, identi.ca — the list goes on and on.

What keeps us interested?

For me, it’s the ongoing developments in technical communication and documentation, and the chance to chat with other technical writers at conferences and other meetings. Thank you to all those bloggers who write about the conferences that I can’t get to!

Here are just a few links to posts about recent conferences:

WOSCON on A Techie Tech Writer Blog
WOSCON by Milo Casagrande
WOSCON by Phil Bull
AODC 2009 by ffeathers
WritersUA 2009 by CyberText
WritersUA 2009 by WritersUA
WritersUA 2009 by ffeathers

Summing up

A technical writer is amazingly, mind-bogglingly similar to Douglas Adams’s Babel fish. So similar, in fact, that most people believe Douglas based his creation on a chance encounter with a technical writer at Cambridge Rentafish.

(babel) fish

The technical writer is probably the oddest thing in the universe. It feeds on brainwave energy transmitted unwittingly by system developers, absorbing their unconscious mental frequencies and translating them into human languages for expansion of its own technical nous. An unforeseen consequence is that if you stick a technical writer in a room full of developers, you can instantly understand anything those developers say. (With apologies to Douglas Adams.)

About the author: Sarah Maddox is one of five technical writers at Atlassian. She writes a blog at ffeathers and lives in a house on a hill near Sydney.

19 Responses

Rhonda

June 24th, 2009 at 5:16 am
1

Nice post Sarah! I’ve got quite a few links on my blog to articles and posts about what technical writers do: http://cybertext.wordpress.com/2008/09/09/what-does-a-technical-writer-do/

And I love the fish reference — after all, I have a fish named after me! A graphic designer colleague in a Brisbane-based company called her fish “Rhonda” in my honour — “A fish called Rhonda”.
Reply
Words on a page » Blog Archive » Use guest posts to add some new colour to your blog - A blog about writing, in its various forms

June 24th, 2009 at 6:55 am
2

[...] (85% of them), most said yes. The rest said yes, but when they had the time. Two of the guest posts have already seen the light of the Web, and the response has been [...]
What makes a tech Writer River

June 24th, 2009 at 8:08 am
3

[...] writers are Jills and Jacks of all trades. But what really makes a tech writer tick? In this guest post, Sarah Maddox explores that question and comes up with some interesting answers. scottnesbitt | [...]
Sarah Maddox

June 24th, 2009 at 5:44 pm
4

Hallo Rhonda

“A fish called Rhonda” — I love it!

Thanks for linking to your list of the things we get up to. There’s a lot of great information there, and some very useful links. I follow your blog feed and your tweets every day.

The post above has a lot of gaps. I’m hoping other tech writers will add comments with more of what makes us so mind-bogglingly useful and/or so ineffably weird.

Thanks Rhonda for starting the ball rolling
Reply
Matt

June 24th, 2009 at 9:31 pm
5

Tech Writers are puzzle-solvers. They ask lots of questions. My one-liner, when asked what really do I do, is “translate from English to English”.
Reply
Andrew Lui

June 24th, 2009 at 9:46 pm
6

Great post Sarah! I think the same characteristics that make us so ineffably weird are also what make us so mind-bogglingly useful.

Most of my friends just nod politely when I talk about the correct use of apostrophes or software APIs. In fact, many people at my workplace would drift off if I tried talking about both of those topics in the same sentence. However, these same strange obsessions give me the opportunity to do what I love every day — write about technology.

I’d also like to add that behind every technical writer’s mild-mannered demeanour lies a rabid chocolate connoisseur
Reply
Anne Gentle

June 24th, 2009 at 11:24 pm
7

Thanks for linking to my blog, I’d love to have people come hang out on the web there. No tech writing aptitude tests necessary.

And how appropriate that the fish gets to swim in the Writer River. Couldn’t resist!
Reply
Sarah Maddox

June 25th, 2009 at 12:13 am
8

Hallo Anne! Heh heh. Lovely pun. Keep ‘em coming!
Reply
Writing a guest blog post « ffeathers — a technical writer’s blog

June 25th, 2009 at 3:22 am
9

[...] leave a comment » Scott Nesbitt has asked a number of technical writers, and I’m one of the privileged, if we’d like to write a guest post on the DMN Communications blog. So I did: What makes a technical writer tick? [...]
Sarah

June 25th, 2009 at 5:02 pm
10

G’day Matt and Andrew!
I love your one-liner, Matt. It illustrates how tech writing is a microcosm of the supreme futility of life, the universe and everything

Hah hah Andrew, great comment. I’m not surprised it was held back for moderation before making it’s late appearance, since it has such an ineffably magnificent vocabulary.

BTW have you noticed how many letters “software APIs” and “apostrophe” have in common? Just 2 odd men out, if you count “ph” as “f”.
Reply
Sarah

June 25th, 2009 at 5:06 pm
11

Eek. Blame the iPhone spelling correction for that horrendous misplaced apostrophe in my last comment. The horror, the horror!
Reply
Milan Davidovic

June 25th, 2009 at 7:11 pm
12

If indeed “technical writers are pretty weird individuals” and “all sorts of people end up as technical writers”, I don’t see how you can make generalizations about them.

Many technical writers work in structured authoring environments, and their output feeds into systems that create outputs that are mapped and formatted by others; on what basis can we say that they “enjoy and are skilled in document design”?

While it may be true that technical writers “have in common a love of and skill in language and the written word”, so do many other sorts of writers; “tailor[ing] your language to suit your purpose, audience and medium” is a key skill not only in technical writing but other forms as well. And are technical writers really so different for actually enjoying writing?

Technical writing to me looks like a broad category of human endeavour performed by a diverse group of people. I think if we were to look at individuals and find out what makes them tick, we would find many similarities to those in other occupations. Perhaps our outputs make us stand out (somewhat), but I don’t believe that what’s under our skin makes us so different. In fact, I think that if we focused on what we have in common with other people, our the goal of meeting their needs would be well served.
Reply
Sarah Maddox

June 25th, 2009 at 10:27 pm
13

Hallo Milan,

That’s a really interesting and well-thought-out comment. I agree with you that generalisations are Not Good. In fact, that belief forms a core part of my being. So, to explain the origin of this light-hearted post a bit: I guess that many technical writers work in an environment where there are just a very few technical writers in proportion to the number of developers and other technical staff. (Of course, performance engineers could say the same thing. And the CEO’s personal assistant, and …) So it’s attractive to some of us to generate a feeling of community by characterising ourselves as a loveable if slightly eccentric “group” of people.

It can be destructive, as history has shown many many times, to set yourself and your peers as a group apart. But I don’t think it’s harmful given the tone of this post.

There are plenty of other ways to get that warm fuzzy feeling about technical writing. It’s a great field to be in.

I really like your point that “if we focused on what we have in common with other people, our the goal of meeting their needs would be well served”. Yes yes yes. Especially in the context of providing user assistance documentation, this is the way to go.
Reply
Sarah Maddox

June 26th, 2009 at 12:56 am
14

Heh heh, here’s an idea for a follow-up post. Instead of “What makes a technical writer tick”, we could call it “What ticks a tech writer off?”

One trigger might be being called weird Another might be that ubiquitous ridiculous misplaced apostrophe.
Reply
Scott

June 26th, 2009 at 7:03 am
15

@Sarah re: “What ticks a tech writer off?” You’ve got the assignment!
Reply
Milan Davidovic

June 26th, 2009 at 8:14 am
16

I admit to often not recognizing when someone is joking or being light-hearted.

I wonder what other ways one could generate that feeling of community…
Reply
Kathleen

August 9th, 2009 at 6:42 pm
17

I just want to say I love this article! I’m currently a senior in university, applying for graduate school in technical writing (trying to go the liberal arts route of technical writing, however, rather than the science/engineering route). This article is witty andamusing; it makes me proud of what I’ve chosen for my career path!
Reply
Fred Williams

August 10th, 2009 at 3:49 am
18

What ticks off technical writers?

1. Waiting until the last minute to decide “this is a documentation emergency” and demanding that the lone technical writer create a flawless user and administration manual without any specifications, no access to engineers, nor any working version of the software.

2. Those who haven’t read a book in years, yet hold STRONG opinions about “writing good”.

3. Those who insiist that “documentation” is a job for losers who aren’t good enough to do “real work”.

4. Anyone who disdains chocolate…
Fred Williams´s last blog ..User:Bradybd
Reply
Sarah Maddox

August 15th, 2009 at 12:12 am
19

Hallo Kathleen and Fred

Kathleen, thanks so much for your comment, it’s great to hear that you enjoyed the article. One of the best bits about writing is when people let you know they liked something. You’ve chosen a great career. There are so many different types of writing, and each type opens up so many possibilities for where, when and how you do it. Good luck with your studies!

Heh Fred, that’s a very good list of tech-writer-tickers-off. Number 1 is par for the course, of course. I guess the sort of situation you describe is what would make us put our fiction writing skills to good use. And number 4? Oh yes!

Cheers,
Sarah
Sarah Maddox´s last blog ..Atlassian technical writers on agile methodology
Reply