h1

Elements of Technical Writing, Part 1

Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing.

Dick Brandon

This section won’t teach you how to write technical documentation Instead, it discusses the elements of the technical writing job—those things practitioners deal with every day—and for each focuses on the one or two things that I think are most important in dealing with that element.

The elements of technical writing are: product, developers, audience, tasks, deliverables, environment, and schedule. Together, they comprise everything important that a technical writer needs to be concerned about. I’ll present them in roughly the order they need to be considered, but recognize that you need to deal with all of them throughout the course of a project. Also, unless specified otherwise, they’re presented from the perspective of the writer, not the manager.

The Product

The product is whatever you’re writing about, even if it’s not a product. It could be a service, software, hardware, an airplane, or a toaster. Regardless, your first job is to understand the product. Read the product specifications, technical requirements, marketing requirements, and documentation for related products. If you’re updating documentation for an existing product, read the existing documentation.

Get your hands on the product. If you’re documenting emergency procedures for the Space Shuttle, you may not be able to give it a test drive, but usually you can get your hands on a sample and try it out. Even with the Space Shuttle, you can probably try the simulator and get familiar with it in other ways.

The first technical documentation I ever worked on was a guide to using the Application Programming Interface (API) for a character-based user interface for the UNIX® Operating System. [1] For those who are old enough to remember, or care, it was the “curses” interface, which was a precursor to today’s Graphical User Interfaces (GUI).

Before I wrote a word of English, I wrote some programs using curses and gave it a test drive. As I recall, I just grabbed some examples written by others and compiled them; no real programming was required. But, I got a feel for what was going on, and I got a test-bed.

You’ll have to figure out the best way to learn your particular product, but however you do it, get as close as you can to the thing you’re writing about.

The Developers

While it’s critical to get close to the product, it’s just as important to get close to the developers who are designing and building the product. Next to the product itself, they will be your most important source of information, and for many projects, they will be your only source of information.

Your relationship with the development team, and especially any assigned contacts, is critical. If your contacts see you as adding value to the product, and even more importantly, if they see you as someone who understands and appreciates what they’re doing, they will do everything they can to help you. If not, they will treat you like Rodney Dangerfield.

Here are a few of the things that I’ve found useful:

  • Use the engineering team’s time wisely:
    • Don’t make them teach you anything you can learn from existing documents.
    • Prepare questions before you meet them.
    • Try to schedule reviews when they’re not in a crunch—this is a hard one, but it’s still worth the effort to try.
    • Don’t ask for additional reviews unless they want them or there are significant changes from a previous draft.
  • Be a visible part of the project. For example, attend planning meetings, participate in discussions about the project, have lunch with the team.
  • Keep the project up-to-date on your progress.
  • As a manager, keep in touch with your engineering management peers. Don’t make your first meeting a cry for help!

If you build a good relationship with the engineering team, you will have a much easier time getting the information and cooperation you need to successfully complete your deliverables. If you build a great relationship, they will tell you about new features long before they show up in a requirements document, they’ll warn you about problems that need documentation workarounds, and they’ll keep you up-to-date on the real status of the project.

The Audience

The audience is whoever you are writing the documentation for. Presumably, this is a group of people who will be using the product in some way. For some products identifying the audience is easy. With the curses API I mentioned above, the audience was programmers who used curses to create user interfaces for their software. For the Space Shuttle emergency procedures, however, the audience could include hundreds of flight crew and ground crew members in a wide range of specialties, each of whom may have a different role to play in an emergency.

Defining your audience is critical to defining the scope of your documentation, the deliverables required, and the resources needed. Therefore, you need at least a rough idea of the audience very early, even if that rough idea is nothing more than: “Homeowners who will use the Flim-Flam 2007 to shampoo carpets.

The project manager or marketing manager should know a fair amount about the audience, but you will probably need to ask the right questions to extract that knowledge. Here are some questions you need to get answered early:

  • What is the job role, or general activity of the person using the product? For example, system administrator, person shampooing carpets, or NASA communications specialist.
  • How will that person use the product? For example, backing up data from a group of PCs, shampooing carpets with the Flim-Flam 2007, or communicating with the cargo mission specialist. At this point we’re talking generally, detailed tasks will follow later.
  • What is that person’s background with respect to the product? For example, entry-level to experienced system administrator, homeowner with no prior experience shampooing rugs, or senior electrical engineer with at least a Master’s degree.

At some point in the process, though not necessarily at the very beginning, find time to talk with some of the audience. This is particularly useful if you’re updating existing documentation and can talk with someone who already uses the product, but even for a new product, you’ll learn a lot if you spend a little time with likely users. It’s also useful to let potential users read drafts of your documentation. This can be tough with some products, but where you can, you’ll get useful information. Regardless, the better you know the likely users of the product, the better your documentation will be.

Part 2


[1] UNIX is a registered trademark of The Open GroupCopyright © 2007 Richard L. Hamilton

Advertisements

4 comments

  1. […] Elements of Technical Writing, Part 1 […]


  2. […] Elements of Technical Writing, Part 1 […]


  3. […] Elements of Technical Writing, Part 1 […]


  4. […] Elements of Technical Writing, Part 1 […]



Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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 )

Google+ photo

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

Connecting to %s

%d bloggers like this: