WORK:Technical Writing: Introduction

JL (or Jean, but I think JL) said, a few weeks ago, that she'd appreciate my contributing a few words on professional technical writing.

I'm going to start here. If people like what I have to say, and give me feedback about it, I'll write more stuff. If not, I probably won't. :)

Let's start with a little history. How I got into technical writing:

A few years ago, JL and Jean and Dancer and I sort of developed a thing where Dancer and I would provide space for simegen.com to start up, and I'd be in JL's and Jean's writing course. I did some writing study with them, then I got well enough to work (I'm a computer programmer), and dropped out of the courses.

It turned out that I wasn't well enough to work. I relapsed a few times, struggled with my health, and eventually got back into programming.

Eventually, I got a job with a company called Cybersource. Cyber gives each of their employees a web page. I didn't want mine empty, so I wrote a set of articles about computer security, aimed at computer laymen.

I mentioned it on LinuxChix, a computer group I'm part of. Then I was emailed by one of the editors of O'Reilly, a major computer book publisher. They liked how I write, and how I explain technical topics in simple English. And wanted me to write for their online magazine.

That's the history. I now write for O'Reilly regularly, and for Newsforge as well.

The O'Reilly target audience is junior system administrators - computer professionals, but ones who might not know the details of my specific topic. By aiming at that target, I don't talk down to senior admins, but don't talk over any professional's head either. The Newsforge audience is broader, and I tend to aim at knowledgable amateurs. They would like to talk to professionals, but accept that they have a large amateur audience as well. I risk talking down to senior professionals at Newsforge, but hopefully not too badly.

Knowing the audience is critical for the sort of writing I'm doing. My job involves:

choosing a topic
splitting the topic into aspects, each of which will fit in 1200-1500 words (O'R) or 800-1200 words (NF)
studying the topic thoroughly
outlining an article or article set for each aspect, so that the topic is presented in a sensible, logical sequence that allows people to put it into practice even if they've only got article 1 of 5
determining exactly what I need to convey in each section of the article
and then finally, writing each section to convey the point for that section.

I also revise, proofread, spellcheck, typeset into HTML, and run the HTML through a validator, before sending the articles off.

The study can involve reconfiguring my machine, writing a small program, or just creating test examples of whatever I'm writing about.

Mostly, I read the manual and test how to use the subject of the article, and then write about what I did.

If anyone is interested in more detail about this, please provide feedback, ask questions, and generally let me know what you want to hear.

Workshop: Technical Writing: introduction

Workshop:
Technical Writing: introduction