Newsletter of the Society for Technical Communication, San Francisco Chapter August/September 2009

Hors d'oeuvres, Round Table Discussions, and Networking
Presented by Susan Becker, Gilbert Gonzales, and Marie McElravy, and reviewed by Sara Greenwald

Members with particular expertise led round-table chats about editing, content management, and Agile development. Moving from one discussion to another, we soon found ourselves posing questions, telling stories, debating and learning energetically.

Editing

Marie McElravy (mamcelravy@aol.com) named her favorite books: a dictionary, The Gregg Reference Manual, and Developing Quality Technical Information. She uses these for the full range of editing, from changing one character to "blowing it up" and rewriting completely.

What is it?

We brainstormed types of edit. Editing for translation catches ambiguous terms and expressions. Editing for consistency ensures that "it's not called a gadget here and a widget everywhere else," Marie said. "You have to make sure in a list of steps that every item is really a step." All of us edit for flow.

Challenges

We debated:

• Is it better for a team to have one editor or several? One makes for consistent style, several for flexibility. There is often no designated editor, so we must all learn to edit well.
• Passive voice -- use it often, seldom, or just about never? Some thought it appropriate in many situations, some in very few.

Solutions

We swapped tips:

• Always print what you write. On-screen editing is only part of the job. If possible, print it and set it aside for a day or so.
• Don't edit your own work unless you must, but if you must, try reading aloud. Good writing has a cadence you can hear. A musician in the group enthused about this.

We all had plenty of ideas about editing as writers, as sometime editors, and often as members of writing teams. Bring up this topic any time you want to get a bunch of tech writers talking.

Content Management

Gilbert Gonzales (www.techpubspro.com) led off the discussion by pointing out that, however little we thought we knew about content management, we all organize content, whether in files and folders or in databases with metadata tags.

What is it?

Gilbert explained that content management systems use databases of topic-based information. Each unit of information has a tag. When the document writer inserts a pointer to the tag, the system brings in the information and gives it the format of the document. "The key is content separated from format," he said.

Challenges

One challenge of CMS we'd all heard about is the need to write for re-usability, so units of information can fit into various types of document. Another challenge is finding a way to tag the information so that a search of the database generates some hits, but not thousands.

Solutions

Database crafters sort information both by subject and by such types as:

• Facts
• Concepts
• Procedures
• Principles

More sophisticated tagging brings bigger heaps of information under control.

A CMS-er in our group reported that the best-loved databases are made by teams experienced at working and tagging together. For a new person on the team, though, learning to use the database "can be a discovery process," because the principles of CMS are "still evolving."

The system's payoff comes when a writer needs to produce many documents on the same topic, fast. A CMS means writers don't have to gather information again or tweeze it out of other documents, but can search, link, and drop it in wherever it's needed in whatever kind of document the client wants.

Agile Development

Susan Becker (scbecker@codewords.com) works with a client company that went Agile several years ago and has become a model of its successful use.

What is it?

Susan invited a group member to describe the pre-Agile "waterfall" development process, in which development plunges as by gravity toward production, and assessment doesn't happen until the product is rolled out. Agile Development proceeds in cycles of development and assessment (called iterations) so teams can revise their goals and methods along the way. Everyone on the team, even the technical writer, has an equal say.

Challenges

Development can stall in frequent but fruitless meetings. Managers used to deadline crunches can turn the brief iterations into a ceaseless rush. One Agile neophyte remarked that short cycles could lead to spinning wheels and never completing a project.

Solutions

Plans need to be general at the beginning and focus as cycles proceed, and this means change needs to be a goal, rather than a source of argument over why the original plan didn't work. Susan's company now devotes the first cycle to designing a plan for succeeding cycle-steps, each with a serious goal.

Susan recalled that years before Agile was born, the best team she ever worked with used an Agile process. It happened naturally. The team motto became, "If it takes longer than an hour, get help." There were no official iterations, but team members set intermediate goals and assessed their work as they achieved each goal. Most important of all, they chatted often, were open about problems, and gave and accepted help freely whenever the need arose.

Commonalities

All three discussions I heard touched a common point: let what works work. The best editing lets us read easily. The best content management puts information where we expect to find it. The best team management lets us work and think and work some more. Whether for editing, structuring content, or managing teams, the most effective methods let us do as we naturally do when we are at our best.

Sara Greenwald (sarapeyton@sfo.com)

| Newsletter Front Page | Newsletter Home | SF Chapter Contacts | SF Chapter Home Page | STC Home Page |