Too Beautiful, the blog

Too Beautiful

| wishlist

Wednesday, December 03, 2008

Career Day: Technical writer

Courtesy a post on the blog of the fabulous and attractive Janice Erlbaum, I came across these five generic questions. You can see for yourself how she answers them from her perspective as a full-time nonfiction writer; I thought I'd give them a try from my perspective.

0) What's your job?

Technical writer at a big software company. I write manuals that tell customers how to install, configure and use our products.

1) When you were in high school, was this the career that you were most interested in? If yes, how did you accomplish your goals? If no, how did you choose this career?

When I was in high school, I had never heard of the job "technical writer," nor was I interested in computers (very few people in the early to mid 70s were exposed to computers, as Malcolm Gladwell points out in his recent book "Outliers," in which he says that the fact that Bill Gates was lucky enough to have a computer at his high school contributed to Gates' destiny), but I was definitely interested in being a writer, already working on short stories and plays. I was in the Creative Writing class in my senior year, and I had been keeping a diary since the beginning of my time in high school.

2) What is the education and training for this career?

Most technical writers I've met are like me: we have had little or no technical training. One of the maxims in the tech writing field is that you can train a writer about software, but it's very hard to train an engineer to write.

The training I had that contributed to my ability to do this job was, mainly, learning to write film criticism, and also training later in life as a high school teacher. From the first, I learned many good writing skills; from the second, I learned good ways to present information.

If you're a young person and think the job sounds good, I'd say the best thing you can do is work on your written communication -- clear, concise, unambiguous writing.

3) Can you please take me through a typical day that you might have?

I get to work around 9:00, screw around for a while reading email, then start tackling something that has to do with my job. There are several ways to start. I could:

Look at a bug report that points out something incorrect or lacking about one of the manuals I'm responsible for.
Look at a specification for one of the new features the engineers are working on.
Work on one of the lists I keep just to keep track of all the different things I have to remember, do, and plan for.

I'll work a few hours, and I usually have lunch around 1:00 or 1:30. There's often a meeting in the morning or afternoon that lasts from 30 to 60 minutes, in which I meet with other employees and share information about current projects, because it helps to have others' insights on how something works (or is broken, which is often the case). I'll work some more until 4:30 or 5:30.

The actual work consists of writing new material, or editing old material, in these software manuals -- which are between 40 and 400 pages of instructions on how to install and use our software. We write the manuals in FrameMaker, and I use a utility called SnagIt to take screenshots of the software as illustrations. We publish the manuals using Adobe Acrobat, creating PDF files, and that's the only way we distribute them -- we don't have paper manuals printed.

In order to write about the software, I have to install, configure and use it myself. I have to talk to software coders, testers and managers to understand why a feature exists and how it works. I have to read specifications -- documents written by engineers and managers that explain how the software should function, and what under-the-covers work they have to do to make it work right. Since those documents are written only for other engineers who are working on the guts of our software, I have to selectively take only the parts of them that the customer -- the "end user" -- will care about.

4) What do you like the most about your job? What do you like the least?

The best thing about this job is the high pay. Starting salary for a junior tech writer is in the 50-60K range. With over 10 years experience, I make over $100K.

The worst thing about the job is working for a huge company with bureaucratic systems that get in the way more than they help.

5) What is the employment outlook for jobs in this career over the next 3-5 years?

Not bad. I thought that after the software industry bubble popped in 2000-2002, I might never work in high tech again. But the industry recovered and I was hired again in 2004 and have been exmployed ever since. The current economic climate is plenty scary, and a lot of people in high tech are losing their jobs -- not me yet, fortunately. But the industry will come back when the economy does.

Other posts in which I write about technical writing:
* Other posts about technical writing

technorati: technical writing, working, jobs

Labels: technical writing, working

Wednesday, August 27, 2008

Yes, it's lucrative

This post on Valleywag lists the going rate for H1-B visa workers hired by Microsoft, and includes the amazing statistics that a developer is paid around $115,000 while a technical writer gets $129,000.

Jesus! I don't make that much. But it is a pretty lucrative field, which provides certain evil consolation for the fact that it takes up all the time and energy that one might better spend being poor and writing novels.

Previously:

On sf.metblogs.com: Zyzzyva editor H. Junker was a technical writer before becoming a litmag editor

On Too Beautiful: What does a tech writer do?

technorati: technical writing

Labels: technical writing, working

Sunday, May 04, 2008

What does a technical writer do?

A year or two ago I met a fellow writer who was interested when I told him that one can make a good living doing technical writing. He asked me for information, and I went home and found a job description, which I annotated with notes. I sent him the following long screed.

You should only read this if you are interested at all in what a technical writer does. I'm sure that does not include most of my regular readers, but someone looking online for the information might find it helpful.

I found this job description from a job posting someone sent me a couple years ago. It provides a pretty good summary of what a technical writer at a high-tech company does. I will annotate it with numbers like this (1) and give some more details.

Outline (1) and write (2) user guides (3) for our software products, with a focus on concise language and meeting audience needs (4). Write detailed software installation instructions (5), including hardware and software requirements (6) and impact analyses (7). Convert (8) user manuals to online help, editing content as needed (9) to meet the standards of this documentation model. Quickly (10) deliver shorter documents, such as knowledgebase articles (11) and compatibility fact sheets (12), to support internal clients (13) like the Technical Support and Sales departments. Edit and proofread material written by other Documentation team members. (14) Work with Analysis and Design team (15) to examine and understand new product features. Work with Education (16) & Services (17) in the development and production of training materials.

1. Some tech pubs managers want you to produce an outline of your manual before you write it. It can be a useful step to make sure you know what you're doing. Fortunately, the outlines of most software manuals are the same: (I.) How to install the software. (II.) How to configure the software, and how to configure your existing environment to work with it. (III.) How to use it. (IV.) Reference section.

2. Writing -- or "authoring" as people sometimes say -- is usually done in FrameMaker, though some companies use other tools. If you don't know FrameMaker going in, they'll ask if you have done complicated publishing stuff with other software, and this is where you'd mention your expertise in Quark Xpress or PageMaker or something. Writing means filling out the outline you wrote in (1).

3. User Guides. Depending on the size of the product, there are sometimes separate installation manuals, performance guides, troubleshooting guides, etc. etc. People who are just learning the tech writing trade are often given either Installation Guides or Release Notes to do before they let you dig into the other stuff. Release Notes are the "read Me" file that you're supposed to read before anything else. It often contains a lit of "known issues," i.e. bugs they couldn't fix before they ship the software.

4. Meeting audience needs is an important concept in technical writing. You always think about things from the perspective of the audience, i.e. the reader of the manual and the user of the product, and *not* from the perspective of the engineer who gave you the dope on how everything works. In fact, this is really the main thing a technical writer does: translate what the engineer said into something regular people can understand.

5. Installation instructions -- I talked about this already, but I wanted to mention that this sometimes means writing the same instructions several different ways, depending on how many "platforms" (or different combinations of hardware and software operating systems) the company says its software runs on. For example, installing the same software on a Windows system and a Unix system is almost always significantly different.

6. Requirements -- This also gets at the point I just made about platforms. Your manual might tell the customer "You must have installed the 1.5_11 JDK before installing this on your AIX system." See also no. 12 below.

7. Impact analysis -- I'm sort of guessing here -- This probably refers to the "cost," in terms of "overhead," of installing the software or various components of it. For example, let's say you installed Google Desktop on your laptop. You probably know that it uses a certain amount of processing overhead to index everything on your laptop's hard drive. Therefore it has an impact on the performance of your computer.

8. Most companies take a manual authored (there's that verb again) in FrameMaker and use another tool to convert it to another format for online help. The tool commonly used for this is something called Quadralay WebWorks, though there is another tool called RoboHelp that I've never used, but which you see a lot of companies using. The important concept here is "single sourcing," which means that the PDF of your manual and the HTML files of the online help come from the same source, your FrameMaker files. And you can see why this is important -- if you had the same thing documented in two places, that's one too many to try to keep in sync. So tech writing departments try to "single source" as much of their stuff as possible. On the other hand, this is sometimes more of an ideal than a practical goal.

9. Editing content as needed -- This might refer to copyediting, or it might refer to the fact that sometimes the automatic Frame-to-HTML conversion tool is not enough, and you need to tweak the HTML help files to make them look right.

10. Depending on how long it takes the engineers to develop a new product -- or a new version of an old product -- you might update a manual only once every 18 months. On the other hand, sometimes other departments want something lickety split, such as the two things mentioned next.

11. Knowledgebase articles. This is a generic term for "the technical information not found in a manual that is sometimes put online for everybody to read, and sometimes made available only internally, to help customers figure out how to do something." The reason a particular fact or procedure might be found in one of these articles and not in a regular manual is that these articles often document rather obscure behavior of the product that you don't want everyone who reads the manual to know about.

12. Compatibility fact sheets are the things, usually in several tables, that tell you that product A works with operating systems X, Y and Z, but only on Windows XP; and on systems X and Z if it's UNIX running a certain flavor of .... you get the idea. With large enterprise software products this gets very arcane and complex.

13. Internal clients, such as the aforementioned Customer Service, and Technical Support and Sales, mentioned here, are also readers of your work.

14. Other team members. Large companies sometimes have whole teams of writers. I work on a team of eight people plus a manager, and we're documenting the products of one division of a company that sells literally hundreds of products. There are, I think, more than 300 tech writers in the company of 35,000 people.

15. By the Analysis and Design team I suppose they mean Engineering, or maybe the people who give the requirements to Engineering -- in other words, the people who decide what the customer wants in the next version of the product.

16. Education. Large companies, and even small ones, have training classes in their products, and sometimes the tech writers contribute to the training materials -- which are totally separate from the manuals they usually work on. Only in the smallest companies -- like the one I worked at for the last two years that had just fifteen people -- are the writers expected to also write the training courses.

17. Services. Companies have "professional services" departments full of people who go to customers and install and configure the products *for* them, because no matter how simple and clear you make your manuals, the product is often too complicated to install and make work the way the customer wants it to.

Whew. If you got this far without wanting to jab pencils into your eyes, you may have the aptitude to be a technical writer. The next question is, how to get the skills. Since it's hard to gain experience doing things like converting FrameMaker books to HTML help without already being a technical writer, the main way you could make yourself interesting to a manager who might give you a shot is to gain experience doing analogous things. For example, if you've ever done a newsletter for a nonprofit group, a school, a community center or whatever, that involves several important analogous skills, even if you weren't using FrameMaker. If you've ever taught someone how to do a fairly technical thing, that counts for something. Look for opportunities to do the equivalent of creating a technical how-to manual. For example, does the school near your house need a simple how-to guide for its staff on using the email system? If you can find *anything* like this to do, it gives you a writing sample, which is probably the single most important thing you can bring to someone who wants to interview you.

OK, enough already. Best of luck.

That's what I sent the poor fellow. It might have been enough to make him run screaming from the idea of ever being a technical writer. But somebody has to do it.

technorati: technical writing

Labels: technical writing

Tuesday, July 24, 2007

Hooked on a feeling

I don't know what the topic of the email was, but on the advertising bar of Gmail today I saw this:

I couldn't resist clicking on it, and wound up at a site with a big advertisement for, not software, but a "course" that promised to teach how to write any book in less than a month. I was particularly tickled by the description of the "Master Writer" behind the course:

Living in his luxurious English home, Nick Daws has been a full-time writer for over 12 years. He enjoys a life of holidaying with his beautiful wife, playing his part as a regional celebrity, and occasionally putting finger to keyboard to write another book.

Oh, la. Eet ees almost too much to touch ze keyboard and write yet anozzer book.

Then there are some of the "WRITING SECRETS no-one has yet told you about":

How to only ever write in FIVE MINUTE segments, so you never lose interest!

Hey, that's just how I do my technical writing. I work for five minutes, then walk around for another five minutes, then force myself back to my desk. I'm starting to get the idea here. You can also learn:

...an ingenious method of injecting instant scene setting into your books, using just two extra words.

Hmm... could they be adjectives? Turning the sentence "He walked across the street" into "He walked across the windy busy street" certainly does inject instant scene-setting.

Why characters are KEY to any book -- fiction and non-fiction!

The course is "your key to a superior lifestyle, 'celebrity' status and industry kudos," an enlightened state further described like this:

Perhaps you're doing it for fame, or the money. It could be you just want to become an industry guru and boost your career. Or it's possible you simply want to become the talking point of a party by introducing yourself as a writer.

Emphasis theirs. I can just see someone reading this and imagining attending a cocktail party where people are whispering to each other "Look -- there's the writer! How I envy him!"

I read much of this out loud today at work to the other technical writers, most of whom are also in writing groups and are working on novels in their spare time. We had a pretty good chuckle. Because the fact is, we are making good money as writers -- minus the scene-setting and the characters, unless the "Transaction Tracer" or the "Report Template Creation Wizard" can be thought of as characters.

Want to really make good money as a writer? There are courses, all right -- like this. But never mind being a celebrity.

Labels: novel writing, technical writing

Friday, March 02, 2007

Saving daylight

Earlier this week I had to get up at 4:15 and be at work at 5:15 for a meeting -- the company is based on the east coast and the project manager there did not deign to take into account the fact that people out here in California are, like, sleeping then.

But not only did I survive this, I have got up at 4:30 twice more this week, including today, because there's no other time to do this contract work I got. And it's actually working for me. I can focus and concentrate. Already I'm done for today.

Now if only I can translate this into a habit and use the early morning time to work on my own writing. I do have a novel to finish.

Labels: contract work, technical writing, waking early, working