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” 😉
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 conversation got better and better. Here’s another screenshot, with the comments shrunk to show just the first few words of each:
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!
Posted on 26 January 2009, in atlassian, Confluence, humour, technical writing, wiki and tagged agile, atlassian, Confluence, documentation, humor, humour, naked tech writer, naked technical writer, technical documentation, technical writing, wiki, wikis. Bookmark the permalink. 4 Comments.