The Naked Tech Writer

Jamie Oliver‘s reason for choosing the title “The Naked Chef” was that it implied simplicity. He wanted to convey the idea that simple recipes are best. Simplicity is something we technical writers strive for too. In choosing vocabulary and syntax for our technical documentation, we’re at least consistently good at dressing down, even if we don’t often go the full monty. So I think we can justifiably claim the sobriquet, “The Naked Tech Writer” 😉

You may remember my agile turtle, original and then re-engineered by Ryan. Here she is again, naked as the day she was drawn:

By Ryan

By Ryan

Tom Johnson has the topic of simplicity well covered. So I thought I’d look into the other possible interpretations of our new nickname, The Naked Tech Writer.

Out there on a wiki

“Naked” might mean “out in the open, for all to see”. If you are writing documentation on a public wiki, as I am, this rings very true.

“Every change you make, every page you break, they’ll be watching you.” 😉

Readers add comments to the documentation pages, and they get to know you by the replies you give. We try to respond to most people’s comments. If necessary, we also update the documentation in response to their requests. Some time later, we remove the comments and our replies.

So while the documentation itself remains unadorned, devoid of personal style (as much as possible), the comments on the pages often do reflect the character of the technical writer. It can be rewarding to converse with your readers like this. Sometimes it’s just plain fun.

Here’s an example of a recent chain of comments on a page in the Confluence documentation. By the time you read this blog post, the comments may have disappeared, so I have taken some screenshots:

The Naked Tech Writer

The Naked Tech Writer

The conversation got better and better. Here’s another screenshot, with the comments shrunk to show just the first few words of each:

The Naked Tech Writer

The Naked Tech Writer

When was the last time you had that much fun with your clothes on?

Baring all in a blog

Quite a few technical writers are keen bloggers. Perhaps it gives us a chance to reveal the more showy side of ourselves. “You see, technical writers do have dress sense after all.” It’s difficult to make documentation look sexy, though some people do manage. But you can dress your blog to the nines.

Dispelling the myth via a photo album

Technical writers are coming out all over the show. Have you seen the photo gallery published by Cherryleaf? “I’m a Technical Writer — Dispelling the Myth”. My team is on page 13. Are you in there too?

I’d be sorry to go back under cover

Sometimes people email me directly, such as when their question relates specifically to their own environment or when it’s “big” question about processes and procedures, rather than something which relates to a specific page of the documentation.

I enjoy this kind of direct contact with the readers. Their comments enrich the documentation. Often I need to go and do some extra research to find the answer to a question. That makes it even more rewarding when I can give the person the answer, and of course update the documentation if necessary.

There are a couple of things on the downside of having such a visible profile. It’s time-consuming, responding to comments on the documentation pages and answering emails personally. At first it was even a bit disconcerting to receive direct emails. But right from the very beginning, even in the first few days of starting work on the wiki, I loved it.

A while ago I received an email from Shirley, who was watching the entire Atlassian Confluence documentation wiki. Such dedication! One day she noticed a large number of page-changes flash past her RSS feed, all with the same time stamp. It looked as if I had changed many pages all at the same time, and she wanted to know what the magic was. She ended her email with:

“And I hope this provides you with a good laugh!”

I explained that I had changed a page name and Confluence had automatically updated all the hyperlinks from other pages throughout the wiki.

And it did give us both a good laugh.

If I ever go back to a less “naked” form of technical writing, I will miss the exposure the wiki gives.

Other ways of undressing

The Naked Tech Writer is here, and here to stay. I’m sure there’s a lot more fun to be had with this nickname. Let me know if you think of any other ways a technical writer gets nekkid. And thank you in advance to WordPress and Akismet for the reams of spam they will undoubtedly trap on this blog post!


About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 26 January 2009, in atlassian, Confluence, humour, technical writing, wiki and tagged , , , , , , , , , , , . Bookmark the permalink. 4 Comments.

  1. I am relatively new to your blog, and I found this post hilarious and insightful. That’s an uncommon accomplishment. Congratulations.

    I love your nekkid tech writer identity. One of the great/powerful/challenging things about writing today is the transparency stew we find ourselves in, with nary a potato cube to hide behind. It’s not just our identities that must be transparent, it’s our processes as well.

    Some of my early jobs were in large documentation shops where tech writers hid behind locked doors (IBM facility security) cranking out streams of language using first generation word processors that were printed on reams of paper and three-hole punched to fit into huge binders.

    One of my first bosses, a man truly clueless about software documentation and anything that would become user experience, gave me the instructions that he would grade my work based on it’s “woomph factor.” This was a term he invented to represent the sound of a large, overstuffed binder hitting the tile floor of his office from waist height. Forget about quality, he only me and my team to produce quantity. How I hated that environment, and how I love the one we have today. Even if I do sometimes shiver from a draft blowing in my direction.

    I’ll be back to see what other brilliance you serve up here, nekkid of course!

  2. Thank you Charlene, what an awesome comment! I love the story about the “woomph” factor. Your entire comment gave me a good chuckle — you have a great way with words. I took a look at your blog too. “Laughing into the Wind“. It’s beautiful.

  3. I love writing “out in the open” for everyone to see with a wiki. Super fast publishing makes life so much easier, even if you have to take a few lumps!

  4. Great read. havn’t had such a good laugh for a long time.
    Cheers mate.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: