Writing Process

The process of producing a manual is a collaboration between the technical writer and the engineering team. Circumstances vary, obviously, but the process usually unfolds thus:

1. I interview the technical experts.
2. We agree on an outline.
3. I conduct in-depth interviews for each topic in the outline. If a coherent specification or draft manual exists already, I can often work from that, too.
4. I write one coherent piece at a time -- often a chapter.
5. The appropriate experts review each piece as I conduct interviews for the next, and then write it.
6. Then we cycle: I edit earlier pieces while writing first drafts of later ones. I receive reviews on earier pieces and ask follow-up questions while later pieces are out for review.
7. When reviews of second drafts come in, we're usually done; second drafts are usually substantially correct and need only minor changes (though very complex information may require another cycle). I ask any necessary follow-up questions, make the final edits, index if necessary, and produce the final manual(s).

The FAQ below answers questions about my competencies, my approach to my job, and other details that are often of interest.

FAQ

What is your job?

1. Learn who the users are and what they're trying to do.
2. Learn the technical information they'll need to do it.
3. Structure the information to support their efforts.

Also:

• Report bugs as encountered.
  I've designed various bug-reporting forms, so I know the details to include.
• Advocate for the user.
  If I notice ways to improve the user interface, I'll say so.

top   bottom

How do you structure information to support the user?

Information design is the essence of technical writing. I'll show you:

In
Email from the engineer reads, in part:

"The host initiates the acquisition of data from the camera by strobing the ENABLE_GRAB bit of the command register. What happens next depends on how the registers have been initialized.

• If the CONTINUOUS bit of the Data Path register is off and both HWTRIG_FLDID and HWTRIG_OPTO are off, then the next single frame from the camera is acquired.
• If the CONTINUOUS bit of the Data Path register is on and both HWTRIG_FLDID and HWTRIG_OPTO are off, then all subsequent frames from the camera are acquired until the CONTINUOUS bit is cleared.
• If the CONTINUOUS bit of the Data Path register is off and either HWTRIG_FLDID or HWTRIG_OPTO is on, then we wait for a trigger signal from the user before acquiring a signle frame from the camera.
• If the CONTINUOUS bit of the Data Path register is on and the HWTRIG_CONT bit is off and either HWTRIG_FLDID or HWTRIG_OPTO is on, then we acquire a single frame from the camera for each trigger signal from the user until the CONTINUOUS bit is cleared.
• If the CONTINUOUS bit of the Data Path register is on and the HWTRIG_CONT bit is on and either HWTRIG_FLDID or HWTRIG_OPTO is on, then we wait for a trigger signal from the user before acquiring all subsequent frames from the camera until the CONTINUOUS bit is cleared."

Out
(Copyright © 1999-2009 by Engineering Design Team, Inc. Reprinted with permission.)

"The host starts acquiring data from the camera by strobing the ENABLE_GRAB bit in the Command register. What happens next depends on the relationship among four bits: CONTINUOUS (bit 4) in the Data Path register, and the hardware trigger bits (0-2) in the Utility2 register. (In the table below, --- means "don't care.")

top   bottom

How do you handle a tight schedule?

When time is tight, we prioritize.

The core of a good manual explains the main ideas, then provides a tutorial showing how the interface lets you manipulate them. I've researched and written such a manual in less than a month. It had a preface, table of contents, installation instructions, glossary, and index as well. In three more weeks, I added troubleshooting information, a user interface reference, and significant additions to everything else except installation.

In fairness, I must mention that the format was in no way exotic, and drafts turned around like lightning.

top   bottom

Can you work remotely?

Sure. Here's how it usually works:

1. Remote projects usually start with a plane ride or a car trip, because the first interview really benefits from high-bandwidth face-to-face communication. It's easier to spot and correct technical misunderstandings, and it helps foster a spirit of cooperation that will really benefit the project later. The first trip is sometimes the only trip required.
2. When I return, I install the software (if any), run it, review my notes, and start writing. I'll email questions frequently, especially at first. The occasional phone conversation may also prove helpful.
3. Within a few days, I'll start sending first drafts. They won't be right, but they'll be close. I will not waste your time or efforts.
4. When I start receiving your reviews, I edit. A first draft can take five hours or fifty; if experience is any guide, the second draft will take much less.

Remote projects require everyone to be a bit adaptable, but they feel like life as usual by now. If you can conduct reviews in an agreed-upon time frame and remain reasonably accessible for questions, I can write you a good document on time.

top   bottom

Will you work on site?

Sure, if you're in the Portland, Oregon metro area. For extended contracts, I may need some help with workstation ergonomics. When writing long pieces from scratch, I'll probably work at home -- it's more efficient that way.

top   bottom

Can you run our software?

It's definitely desirable that I do. I'm set up for Macintosh and Windows. For other platforms, we can make arrangements.

I'll need installation instructions, I'll ask lots of questions, and I'll report bugs.

top   bottom

Can you use [insert name of tool here]?

At the moment, my proficiencies include:

I've been learning new tools to do the same kinds of tasks -- writing, typesetting, online presentation -- for over twenty years now, and I haven't yet met one I couldn't use. Given the galloping change in high tech, most projects include the need to learn something new. That's fine with me. It keeps things interesting. It seldom slows me down.

My most extreme case of novelty occurred in early 1996: Intel's Indeo® video Web site. I was putting together my first large web site while working with a new operating system (Windows 95®), a new email application, several new editing applications, new technical information (my first exposure to codecs), new procedures, and (last but not least) new people.

The project was done in four calendar months, with slightly over 400 hours billed. My colleagues at Intel were satisfied with the pace; they called me back twice.

top   bottom

Can you illustrate?

Not well. I can make diagrams with boxes, lines, and arrows, and anything with tables. More sophisticated figures are beyond me. I made the graphics for this web site, but they use techniques not ordinarily helpful for technical illustrations.

I can work with an illustrator of your choosing or mine.

top   bottom

Can you program?

Short answer: No.

Longer answer: Give me a hundred syntax examples, and I will probably find the ones with syntax errors (though not semantic ones). I wouldn't skip QA on that account.

If a tutorial needs a running application, I cannot write it. The pinnacle of my programming prowess is a feeble JavaScript menu bar. I got an A in Pascal in 1984 and decided I did not want to spend the rest of my life catering to a fussy compiler. The world struggles with enough mediocrity. Few writers can explain technical concepts the way I can. Improve the universal competence level: hire me to write, not to program.

top   bottom

If you can't program, how can you write a programmer's guide?

I can understand the confusion. But let's be clear about the task: to write a programmer's guide requires knowing how to write a manual. If the developer knows how to do so, and chooses to spend the time and effort to write a thorough manual, that may be the best of all possible worlds. The next best, however, is a writer with a deep understanding of programming and programmers.

In writing a programmer's guide, developers typically face three big problems:

• They often dislike writing and either postpone the unpleasant task, or rush to get it over with.
• The schedule often demands frequent interruptions for bugfixes or redesign.
• Most important, they have long since forgotten what it's like not to know: It's hard to explain water if you're a fish who's been swimming in it forever.