Social Enterprise

Does having a blog make you a writer?

For the techno-savvy TechRepublic member, writing in some form or fashion is an almost daily occurrence. But how effective is your communication? In this interview, author Barry Rosenberg shares his thoughts about the current state of technical writing skills.

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.

About Mark Kaelin

Mark W. Kaelin has been writing and editing stories about the IT industry, gadgets, finance, accounting, and tech-life for more than 25 years. Most recently, he has been a regular contributor to BreakingModern.com, aNewDomain.net, and TechRepublic.

Editor's Picks

Free Newsletters, In your Inbox