Posts

Posted on

Ins And Outs of the Technical Editing SIG Web Site

In keeping with our promise to provide an article on watercooler chats, here is a summary article of the most recent watercooler chat. This chat was held on May 12, 2010, and it focused on using the TE SIG Web site.

Two Cool Site Features

Rick Sapir, the TE SIG webmaster started out by highlighting the two “cool” items on the site.

  • Use of IRC (Internet Relay Chat) chatting system
  • Mirroring of the discussion list with the SIG website forum, tweets, and Linked In

Two Important Things To Know About Our Site

Rick also mentioned the two important things to know about our site.

  • First, just about everything and anything related to the SIG is available on our site.
  • Second, the site is not the only way to get information. Much of the information on the site is automatically syndicated to Twitter, LinkedIn, RSS, and our mailing lists.

Becoming a Site Editor

Chat participants were encouraged to use the wiki. Rick indicated that all pages on the site are wiki pages. He stated that anyone could volunteer for the role of a site editor, and it was easy to create, update, or edit pages. However, Rick mentioned that for some reason, it seemed like people were hesitant to do so. Rick felt that the hesitancy is unwarranted because it is impossible to break any content and it is very easy to undo a change on our Web site.

Getting Past Being Overwhelmed

The TE SIG Web site has certainly improved over the past two years! However, Rick commented that based on the results(external link) of a recent Web site feedback survey, it seemed like some users felt that there was so much “stuff” that they did not know where to begin. One of the opinions expressed in the chat was that a newsletter article would help.

As a follow up, this summary article indicates what you can do to navigate through the Web site more easily.

For the interesting perspectives that were exchanged on the chat, you can see the chat transcript.

Posted on

Creating a Style Guide Advisory Group

Andy Werth

Technical editors often must create and maintain a company or department style guide. Good editors know it is crucial to draw on colleagues to help determine effective style guidelines.

For example, if an editor doesn’t know what to call an unnamed button in the user interface, it may be best to ask the customer service team how they and the customers refer to the button and add this name to the style guide—a method far preferable to simply making up a name. For guidelines about how to refer to the company’s products, the marketing department might be the best source. Many groups in your company—IT, engineering, programming—can be a valuable resource as you build your style guide.

But getting thoughtful, punctual responses from colleagues about style questions can be difficult. This is especially frustrating when a document is on a tight deadline. A large company with an established documentation department may not have this problem; SMEs, or other editors, can often be queried for quick answers. However, if you’re a lone editor with few resources, you must draw on personnel throughout your company to establish effective guidelines.

In that case, you may need a Style Guide Advisory Group. In my experience, a Style Guide Advisory Group:

  • Reduces the time colleagues take to respond to your questions and increases the number of responses. (This may be because being part of a recognized group helps establish accountability.)
  • Encourages a sense of ownership in the style guide across teams, making it more likely that people will want to contribute to its success.
  • Ensures that style decisions address readers’ needs.

The following six steps will help you assemble your Style Guide Advisory Group.

Make the List

Make a list of personnel who you think would be a good fit for the group. Try to include one person from any group you depend on for product or end-user knowledge. If you’re not familiar with anyone in a particular group, ask coworkers for a recommendation.

Make the Pitch

Once you’ve made a list, approach each person. Explain why the group is important and why you think they’d be a good fit. For example, mention the high quality of their other work, their attention to detail, or their deep familiarity with many products.

Explain the time commitment honestly. Try to limit their commitment to about 15-30 minutes per week; anything more may be asking too much of people whose time is already stretched thin. Stress that most communication will be through e-mail (this can do wonders; for many, “meeting” is a dirty word). When explaining the time commitment, remember that it will probably be greater if you’re just getting the style guide off the ground.

Ask the Boss

Once they’ve expressed interest in the group, talk with their supervisor. (In some organizations, protocol may require that you speak with a supervisor before approaching their subordinate.) Emphasize the group’s value to their team. If you’re speaking with a customer service supervisor, stress that effective documents can reduce the number of calls from end users, and explain how a customer service team member will help documents achieve this effectiveness.

Once you’ve emphasized the group’s value, clearly define the time commitment. If you’ve made a persuasive case for the group, you’ll find that most supervisors will allow their team member to participate.

Put it in Writing

Once the group is assembled, send a welcome e-mail that states the group’s purpose, guidelines, and expectations. Guidelines might include specifying how they should respond to your questions. For example, should they respond only to you, or should they copy other members on their response and participate in a cross-group discussion that you moderate? Expectations might include that they respond to each question, that their response be carefully considered (a quick response that’s poorly informed is worse than no response), and that they respond by the deadline.

Put it to Work

Once your group is assembled, start submitting questions. A few guidelines:

  • Don’t bother group members with queries outside their area of expertise; not all queries must be sent to every member.
  • State your question clearly. When possible, anticipate what their answers might be and phrase the question in a multiple-choice format. This allows them to choose a letter rather than type a long response—but make it clear they don’t have to choose among the answers you’ve provided.
  • Include the day and time by which you’d like a response. It may help to add a reminder to your calendar to “close” the question.
  • When the response time is up, evaluate the answers and send your decision to everyone to whom you sent the question. Explain your reasoning. Before announcing your decision, wait until either you have a response from everyone or the due date has arrived.
  • Always thank them for their time.

Make it Better

After the group has been in place for about six weeks, send a quick survey to the members. Ask whether their expectations about the time commitment are being met and request suggestions for improvement.

Once you’ve established your Style Guide Advisory Group, you’ll likely find that the number of people who respond to your style questions increases, the time it takes to get responses decreases, and your company’s style guide—and therefore your company’s documents—are more effective.

Posted on

Technical Stylist’s Tip: The Diagramless Diagram

Kathy Underwood

You know the kind of paragraph that seems to resist all your attempts at editing? Its sentences are usually filled with noun stacks (filled with abstract nouns), pronouns without clear antecedents, and passive voice—not to mention multiple independent and dependent clauses. You just want to write “awk” in the margin and move on, right?
The problem, of course, is that “awk” says no more than “This sentence makes me unhappy.” So what can you do to help both yourself and your writer to untangle a big sentence mess?
Over the years, I’ve adapted a technique to create a “diagramless sentence diagram” to help analyze problem sentences. Because sentence diagramming is not widely taught any more, I wanted to provide a visual representation of the sentence structure that could be used by writers who had no diagramming experience.

Let’s try this bit of bureaucratic reportage, which bears all the signs of a first draft:

Following a series of well-attended information sessions concerning the new multi-user features as well as other enhancements, user group members were invited to review and evaluate a project plan for the new users’ Web site to be established during a public forum sponsored by the Steering Team last Friday. However, the Steering Team was disappointed when only 2 of the 50 users were in attendance and because no questions were presented to the expert team assembled for the occasion.

“Awk” doesn’t begin to describe the problems in this paragraph. So let’s try to find something substantive by first identifying actors and actions as represented by the subjects and verbs.

sentence 1

  • actor user group members
  • action were invited to review and evaluate

sentence 2

  • actor the Steering Team
  • action was disappointed

At this point, we know that there are some users who’ve lost interest in whatever it is that the Steering Team is doing and that the Steering Team is disappointed. And if they all talk like these sentences are written, we know why. So let’s see what else we can dig out from those sentences.

sentence 1

  • actor the Steering Team
  • action were invited to review and evaluate
  • when “Following a series of . . . sessions . . . concerning . . . features”
  • why “to review and evaluate the project plan”

sentence 2

  • actor the Steering Team
  • action was disappointed
  • when “when only 2 . . . were in attendance”
  • why “because no questions were presented”

This far into the analysis, we should be seeing something meatier. What are we missing? The subject of the meeting—the actual topic about which there’s a lot of apathy, disappointment, and, one infers, smoldering resentment.

Note that as you identify additional key bits of content, your idea about the meaning of the text may shift significantly. Not infrequently, you’ll find that a writer will have buried a significant detail in a dependent clause or at the end of a prepositional chain. Also note that you might find that the explicit topic might be incidental to the real point of the sentence. It’s highly likely in such cases that you will need to query your writer.

So here’s a quick fix, admittedly done without the writer’s response to your carefully worded query and with a rash number of assumptions:

After the sessions on the new product release, the Steering Team invited user group members to ask questions and offer comments to an expert panel. The panel’s report will serve as the basis for services on the new product Web site.

The little set of labels (actor, action, when, and why) won’t rewrite the sentence for you. But they can at least help you tease out important details that seem trivial, thus enabling you to realize whether the writer might have hidden the real topic in the least significant parts of the structure.

I would like to add that this primitive analytical tool I’m using pales in its utility next to the real thing—sentence diagramming. For those of you who weren’t fortunate to be exposed to diagramming in school (and even if you were), I recommend Kitty Burns Florey’s Sister Bernadette’s Dog Barking: The Quirky History and Lost Art of Diagramming Sentences.

Posted on

Do Your Magic!

Charles R. Crawley

By title at the avionics company where I work, I am a technical writer, but by function I am really a technical editor. And the engineers at my company often see me as a magician. They bring documents to me and ask me to do my magic on them.

Based on a posting on our Wiki, “Understanding the Value of a Technical Editor”, I would like to point out a few indicators about our worth and magical appeal.

First, my company is getting its money’s worth. I don’t know how the economic recession is affecting you, but it’s about to make my hands fall off. In less than half a year, the other technical writer and I have produced almost as many pages as we did IN THE ENTIRE LAST YEAR (emphasis added). Working harder (albeit, smarter) seems to be our alternative to hiring another writer.

Second, we are the masters of the documentation system that controls our documents. While I never intended to be a database administrator, it is in fact what I have become. We understand and control (to a certain extent) the review cycle better than anyone else. Engineers and managers always come to us to find out where something is “stuck.”

Third, we provide a level of quality control that is easily lost when non-writers take over the process. Inevitably, we fight over control of the Word documents (source files) and insist that engineers review Adobe Acrobat files, which are copies of the Word files. Whenever we lose control of this process, documents invariably get messed up in one way (writing) or another (formatting).

While I am thankful to still have a job, I am not happy with the amount of work we do because it has lead to a loss of focus on the actual writing. But I know that we contribute to the financial bottom line of our company. And I know that without our documents, equipment will not get certified, planes will not fly, and people will be even more unhappy with the airline system than they already are.

Also see, Understanding the Value of a Technical Editor(external link).

Posted on

Bette Frick’s Marketing Bingo

Carol Lamarche

Bette Frick’s upbeat webinar, “Marketing Bingo,” was the first Technical Editing SIG quarterly membership meeting of 2010. In her engaging presentation, Frick, the Text Doctor®, presented 25 marketing strategies that every editor can use.

The strategies ranged from passive to active techniques. Key points included:

  • the relationship between trust and branding
  • marketing as a process
  • the importance of investing in marketing
  • old and new traditions in networking

The webinar presentation was based on a bingo game. A bingo card, consisting of 25 squares representing different marketing tactics, was supplied. Webinar participants (marketing bingo players) who scored “bingo” were eligible for a prize.

The downloadable “Marketing Bingo” handout, including bingo card and accompanying notes, is currently stored in the SIG archives at http://www.stc-techedit.org/file20(external link). An audio file for this presentation will not be available.

To review the “Marketing Bingo” presentation, download the handout and see the interview with Frick below.

How is branding a “trust mark,” or how is branding related to trust?
I am almost addicted to my brands. I’ve had three Saturns (unfortunately, GM killed that brand recently). My first Saturn was so good to me, I just kept coming back for more. I’ve had this Saturn for 5 years and have never had one single repair in that time. I probably would have driven Saturns until I went into the nursing home!

I’m the same way with my HP products. I have two HP printers and an HP laptop, and I just bought a brand-new HP laptop. I trust the performance and the support.

In the same way, we independents can establish our brand. Think about what you like in the brands you are attracted to and purchase. For me, it’s not about being flashy—just the opposite. I like dependability, a good price, surprising features that I didn’t know I needed or wanted, and good support. We can provide all that to our clients. Dependability means quick turnaround of documents when possible and always a quick response to e-mail. I price my editing and my training classes fairly (not at the high end). There’s always someone less expensive and always someone who’s more expensive, but there’s never someone better! And so on … All businesses have a brand. I want to make sure mine is a positive one.

You talk about the “new business cards,” such as Web sites, social media, blogs, podcasts, and webcasts.
a) How important are these to editors?
I think these can be as important as you want them to be. For me, my blog is a great opportunity to prewrite my newsletter articles with an audience in mind; it’s different than writing in my journal. The webcasts are a way to highlight my teaching skills. For others, Twitter, Facebook, and other venues may suit their style and their businesses well.
b) Can we make it in business without these?
Sure, you can make it in business without any of the marketing tactics that I suggest. I simply couldn’t or wouldn’t give up my LinkedIn. It is too productive for me in uncovering leads into companies where I want to find work.
c) For people who aren’t familiar with producing or marketing with these, where would you suggest we start?
As a trainer, I believe the key to better performance is always—you guessed it—TRAINING! Take a local or online class about any type of marketing that you don’t understand. You’ll find it’s not so mysterious, and you’ll come away with a list of action items to make that particular method work for you.

Could you say a few words about Point 4, “Listings on others’ sites”? (It’s not explained in the notes.)
The only problem with listings on others’ sites is that if you complete the listing and sit back, waiting for the phone to ring, you’ll be disappointed. Do your best to create an attractive, persuasive, dynamic listing, and don’t count on ever getting a response. Then, when you do, BINGO! I found my book designer for my Marketing Bingo book, Greg Field, on a listserve for Boulder Writers’ Alliance (I posted a small ad). Just last week, Greg asked me to provide a reference for someone who found him through his Rocky Mountain Publisher’s Guild listing. I provided a glowing reference (Greg’s wonderful); he got the job; BINGO! He’s gotten two jobs through me through networking and listings.

Since I’m itching to get into the ground with my organic garden (and snow is predicted for this week), I’ll liken listings to gardens. You won’t get produce unless you plant seeds. A listing on someone else’s site or in a book of freelancers is a seed. You may get something green from it, but not every seed produces growth. (Not to mix metaphors, but if you went fishing without bait, you wouldn’t catch many fish, would you?) Enough with the metaphors.

In Point 23, “Be elected to leadership,” you mention that we should be careful to strategically select the organizations that we serve. What are the marks of a good fit?
It would be smart to lead a group of your peers (editors, perhaps). It surely will enhance your credibility if you succeed. It would be even smarter to provide leadership for an organization where your clients hang out. I volunteer for the Boulder Area Human Resources Association because HR managers, directors, and vice presidents appear at the meetings—and it’s those people who hire trainers.

You mentioned that editors and other technical communicators who are on a payroll often don’t think about how to get credibility or publicity, and are often the first fired during cutbacks. How can we market ourselves within our organizations?
You can use every one of the 25 Marketing Bingo tactics! You can write blogs for your organization; you can then turn the blog posts into newsletter articles. You can volunteer to work on the company Web site. You can organize, sponsor, or underwrite events. You can work at your company trade show. You can be elected to lead groups within your company’s industry. It’s all good—and it will gain you credibility and good publicity. You’ll build a brand of being the “go-to” person; you’re the one who really knows what’s happening and who’s who; you’re indispensable. Then sit back and watch your career blossom.

You plan to publish your Marketing Bingo concept in a book soon. What will readers find? Why should we stay tuned?
Yes, the book is in process. I’m on the third draft, and graphic artist Greg Field is working on the design. Readers will learn more about how each Marketing Bingo tactic might work for them, and they’ll learn tips for implementing each tactic in their own business. They’ll find links to other sites for further information and tips on each tactic as well.

For me, the good news is that I have so much business this spring (through careful Marketing Bingo promotion) that I don’t really have time to devote to the book right now. This is not a bad problem to have!

Although the webinar has passed, may people who use your marketing bingo card still contact you for a free gift?
Sure, if they tell me they made “bingo” by being willing to use a tactic or actually doing it … if they get five tactics in a row, they get bingo!