When
historians write about the information age many years from now, among the
phenomenon discussed will likely be the resurgence of writing as a daily
endeavor. Whether it is blogging, posting in
discussion forums, or just plain e-mailing, the industrialized world now spends
a great deal of time putting words to pixels. In many cases, this written
communication moves beyond the ordinary business chatter to cross into the
category commonly known as technical writing.

However, as
more and more individuals take part in these technical writing assignments, the
need for training and skill development becomes more apparent. Communicating a
technical idea, and communicating it well, requires a little more thoughtful
reflection than sharing a custard pie recipe via e-mail with your mother. (Maybe not—neither I nor my mother ever baked a custard pie
so I’m just guessing).

In his
book, Spring into Technical Writing for Engineers and
Scientists, Barry Rosenberg explores the ins and outs of technical writing
including topics such as judging an audience, jargon, and active voice. The
principles outlined can be applied to proposals, manuals, lab reports, Web
sites, and even your blog. Chapter 16, PowerPoint
Presentations, is available as a free TechRepublic download.

In the
following interview, he shares with us his perspective on current writing
standards, curriculums, audience assessments, code documentation skills, and
presentation pitfalls.

Title: Spring
into Technical Writing for Engineers and Scientists

Author: By Barry Rosenberg

Publisher: Addison Wesley Professional

Chapter 16: PowerPoint Presentations

ISBN: 0131498630; Published: May 17,
2005
Copyright 2005

Web site

Interview

[TechRepublic] Growing up, my English teachers
stressed the principles found in Strunk, White, and Angell’s Elements of Style. Do the established principles
of style currently taught in high school and universities apply to technical
writing or is a change of curriculum really needed?

[Barry Rosenberg] Yep, three of my college professors
assigned Strunk and White (pre-Angell)
as ancillary reading. I stubbornly ignored it. Later, when I began to write
professionally, I finally opened up the book and discovered how truly amazing
it was. Many years later, when I started teaching a writing course at MIT, I
returned the favor by assigning the book to my own students. And guess what?
Sweet karma—my students ignored it.

Sorry for
that digression. I believe that the lessons in Strunk
and White are still quite valuable for any writer, technical or otherwise.

Do we need
a change of curriculum? Well, in general, I think writing instruction is much
better now than when I was a high school student. That said,
I would like to see students spend a bit more time learning to describe simple
objects through prose. Consider that when you take an introductory drawing
class, you draw simple shapes. Similarly, when you begin music lessons, you
learn scales. By contrast, when you take an introductory writing class, you
typically start by writing some sort of opinion piece. (It is kind of like
starting an introductory drawing class by asking students to produce a work of
impressionism.) I’d love to see introductory writing classes ask students to
compose a 150-word description of a thumbtack or a paper clip or a ruler or
a…

[TechRepublic] Taking the time to learn and know
your audience is one of the first suggestions you make in your book. In
information technology circles, we sometimes make unfortunate assumptions about
the level of general knowledge in an audience, especially when it comes to
jargon. What advice can you give to TechRepublic members regarding how to learn
an audience? Are there successful techniques that one can apply to each new
situation?

[Barry Rosenberg] Yes, figuring out your
audience–who they are, what they already know, and what they need to know—can
be very difficult.

For many
projects, it is wiser to see “the audience” as actually being “a
set of audiences.” For example, in the enterprise software world,
technical writers usually divide the audience into sets of end-users, system
administrators, database administrators, system integrators, and so on.

Each of
these categories are often broad. Some end-users, for
example, are awfully savvy with a computer, while other end-users are
completely technophobic. The wise technical
communicator finds a way to reach both ends of the spectrum by comforting the
phobic with simple, easy-to-understand, jargon-free explanations and engaging
the savvy with interesting tricks and hacks.

[TechRepublic] One area of concern for
TechRepublic members is in the realm of programming and code documentation.
While the audience for code documentation is small, it can be extremely
important for debugging and updating important software systems. What advice do
you have for documenting code?

[Barry Rosenberg] As a technical writer, I read a lot
of code comments and generally find them quite cryptic (when they exist at
all). Some programmers mistakenly believe that their code is self-documenting
and that textual comments are a redundant waste of time. Of course, if those
same programmers are forced to revise their own code a few years later, they
might long for well-written comments. 

The
following are a few general suggestions for improving code comments:

  • Think of the code itself as
    part of the documentation process. If the programming language allows long
    names, give all procedures and functions a clear, detailed name. For
    example, name a function “CalculateCoefficientOfStaticFriction”
    instead of “Frict.” If possible, give
    the routine a name that starts with a verb.
  • Establish commenting
    conventions throughout an engineering group. As part of the nightly or
    weekly build process, run a script that reports errors when these
    commenting conventions are broken. 
  • Provide a comment in front of
    every routine name. Describe the purpose of the routine using complete,
    grammatically correct sentences.
  • Provide a comment that clearly
    describes every input and output parameter.
  • Provide a comment in front of
    every loop.
  • Provide plenty of examples.
  • Consider having another
    programmer (or technical writer) write the comments. After all, it is
    sometimes quite difficult for the person writing the code to provide
    useful comments.

[TechRepublic] In the chapter we are featuring for
download, you discuss PowerPoint and the aspects that make a successful
presentation. I think I speak for many TechRepublic members when I say there is
a tremendous need for help in this area. Why do PowerPoint presentations,
presumably constructed and presented by normally bright and engaging people,
often fail to capture our attention? Is PowerPoint an underdeveloped skill that
can be enhanced with training or is it the presentation format itself that
needs to be re-thought?

[Barry Rosenberg] We’re living in a short attention
span era. People make snap decisions about television shows, cycling through 50
channels in a minute. Similarly, people click away from Web sites as fast as
they click into them. So, in this context, along comes poor Sally from
Marketing with her PowerPoint stack. The projector goes on, the lights go out,
and the audience goes to sleep. Why? Well, to the audience, Sally’s PowerPoint
presentation comes across like a very low-bandwidth television program—the kind
that every viewer would click out of quicker than you can say “universal
remote.” 

Is there
hope for poor Sally? Can she hold the audience long enough to get her message
across? Yes, it is possible, but only if she learns skills such as the
following:

  • Learn to see her time slot as
    an interactive session rather than as a one-sided presentation.
  • Learn to surprise the audience.
  • Learn to mix the kinds of
    information that appear on slides to appeal to a wide range of audience
    members.
  • Learn to write ultra-clear
    bulleted lists.
  • Learn to mix a little humor
    into the presentation.