Tag: Vol 7 No 5

Posted on

Keeping up with the Joneses (or Is It Joneses’s?)

Justin Baker

It’s important to keep up with your fellow technical communicators; one should be up-to-date on all of the latest advances in the technical-communication profession. But sometimes we can get too caught up in the latest professional advancements—XML, DITA, information architecture, online help systems, metatags, user-interface eye tracking, etc.

Among all of these sophisticated, bewildering advancements, verbal text (words and paragraphs) is still one of the basic building blocks of technical communication, and good grammar is what makes verbal text solid and valuable. As a result, a good grammar refresher is needed from time to time.

There are many educational tools that can provide such a refresher. One tool that I have found particularly helpful is the Bedford/St. Martin’s Exercise Central 2.0 Web site (http://bcs.bedfordstmartins.com/exercisecentral/(external link)). As you may know, Bedford St. Martin’s publishes the informative Handbook of Technical Writing. When you access the Exercise Central 2.0 home page, you will notice that you have to log on to the Web site. To do so, you need to sign up as a either a student or an instructor—don’t let this deter you. Sign up as a student. If you don’t log in, only limited content will be available to you. (Note: I contacted the Web site’s staff to determine if use of their Web site by common users is a violation of their policy; a staff member stated that it is not against their policy for the Web site to be used by someone who is neither a student nor an instructor.)

Once you are logged in to Exercise Central 2.0, it will be important to note the Tutorials and Exercises hyperlinks under the Web site’s banner at the top. These sections will provide you the educational meat you’re looking for. (The Diagnostic and Scorecard sections are primarily for students and instructors who need to view reports of exercise scores.) The Tutorials section gives you a great refresher on common grammar rules (in addition to usage and style issues), so take that first if you are particularly rusty on grammar. After you have taken the tutorials, the Exercise section allows you to test your grammar knowledge. The exercises are usually 10 questions each with easy option clicks to speed each exercise along. Simply click Submit once you are done with the questions, and you immediately get your score. Exercise Central 2.0 is a very lean, easy method for exercising your grammar knowledge.

Another tool that I have found particularly helpful is Diana Hacker’s Grammar Exercises Web site (http://bcs.bedfordstmartins.com/rewriting/ge3.html(external link)), which is related to Hacker’s book A Writer’s Reference published by Bedford/St. Martin’s. Again, these exercises serve as a refresher on more than just grammar (if you consider grammar in its strictest definition: how words and phrases function in relation to one another to form a coherent language); exercises on usage and style (word choice and sentence style) are also present. Unlike Exercise Central 2.0, these grammar exercises do not require registration. You are prompted to provide a name each time to sign on, but, technically, you don’t even have to do that. Once you have selected an exercise from the exercise menu, either type a name (any name), and click Begin, or don’t provide a name, and click Begin. Diana Hacker’s Grammar Exercises has a slightly more contemporary instructional design with the employment of hyperlinks rather than option buttons, but the overall design is the same—10 questions with easy answering for a streamlined educational experience.

Sometimes our heads can get lost in the proverbial clouds of technical advancements, especially publishing-format advancements. It’s important to periodically ground ourselves and remember some of the basics of our profession. Those basic building blocks include verbal text and grammar. Bedford/St. Martin’s Exercise Central 2.0 and Diana Hacker’s Grammar Exercises can help you get reacquainted with those building blocks.

Posted on

Foreign Words: To Accent or Not to Accent

Lisa Adair

Recent postings to the discussion list brought about a lively debate on the use of foreign words in technical writing. Accented letters occur frequently in foreign words. When writers don’t include the original accent marks, words like résumé become resume, thus creating ambiguity.

One of the posts said that non-native English speakers are pushing for the retention of accent marks. However, it does pose the question of where does it end? Should Greek words appear in the Greek alphabet? Should Russian names appear in the original Cyrillic script? What about “sounds” that are indicated with accent marks?

Plural grammatical features from other languages also become an issue. Is it forums or fora, antennae or antennæ, indexes or indices, appendixes or appendices? Most postings agree that context plays a large role in which spelling you choose. And words like wunderkind would never be pluralized as wunderkinds, but would be wunderkinder per native German.

Editing guides typically don’t get involved in these types of questions. Microsoft Manual of Style advises against using foreign words and phrases since they’re typically not understood worldwide. If your audience is not as diverse, foreign words and phrases might be perfectly acceptable.

Good dictionaries (American Heritage, Fourth Edition) list foreign words. Some German words like bildungsroman, zeitgeist, schadenfreude are listed as acceptable whether or not they’re capitalized. They also track the evolution of words quite well, even if they trail actual usage. For example, Rôle became role as it passed into the English language.

Generally speaking, everyone agrees that using original alphabets in scholarly works is acceptable, but will be viewed as annoying in technical writing. However, proper nouns should be written in the original alphabet as much as possible to respect the capitalization and markings of people who use them, that is, André Breton as opposed to Andre Breton.

Posted on

Book Review of “Effective Onscreen Editing” by Geoff Hart

Virginia Janzig

Geoff Hart’s book, Effective Onscreen Editing (Diaskeuasis Publishing, © 2007), is a readable and useful addition to the general literature on how to be a good editor.

Editor’s Note: To learn more about the book: http://www.geoff-hart.com/home/onscreen-book.htm(external link). To purchase a copy of the book: http://www.geoff-hart.com/download/buy-eoe-book.htm(external link). Geoff is currently revising the book to incorporate review comments that he’s received, fix some infelicitous wording, and incorporate some new stuff he’s discovered since the book was released. Details of these changes and corrections at: http://www.geoff-hart.com/resources/eoe-may2007-errata.htm(external link). The new version should be available online by 11 January 2008 if all goes well. At that time, all purchasers of the previous version will be contacted and offered a free upgrade to the new version.

His main points are that onscreen editing can be fast and effective and can reduce errors when edits are incorporated.

Three of the main topics of the book are what onscreen editing is, what its advantages are, and how to implement it for yourself and introduce it to your team. The focus of the book is how to edit onscreen using Word for either the PC or the Mac.

The book describes using the software tools, editing nonstandard files, editing with software other than Word, finding and using research sources, and safeguarding your work and health. Other topics include information on working with clients and additional detail about Word software.

The book has two primary audiences:

  • Those who have never edited onscreen and need to know how and where to begin, how to be effective, and how to use the tools
  • Those who are currently editing onscreen but want hints and tips on how to be more effective, both with tools and with clients

Most of the information on tools, basic editing techniques, Internet resources, security information, and health concerns is available but can only be found in separate sources. Geoff Hart’s contribution is to bring these topics together in one manageable book and to explain them from an editor’s point of view. He has done an excellent job of describing not only how to be an effective onscreen editor, but also why this methodology is advantageous to our profession. Those managers and editors who are new to this kind of editing can use this book as a set of guidelines to help them understand why and how to implement this technique. Those who already are familiar with onscreen editing can browse to find specific information on new tools, new ways to use familiar tools, how to work with nonstandard files, and much more.

The book has a strong emphasis from the point of view of an independent editor and provides a great deal of information on working with clients. Many of the issues are not relevant to editors in a corporate environment but can be easily passed over.

The chapters on tools, resources, and security provide clear procedures and workarounds. Geoff Hart covers all the tools in Word and how to use them effectively and efficiently. I knew many of them but was surprised and delighted to find some new ones. I also found several ways to improve my use of some of my current tools, such as search techniques, creating effective comments, and using style sheets and exclusion dictionaries. In most cases, I had to test several of the recommendations, which slowed down my reading, but proved that the time and effort were well worth it. For example, on page 215:

“Word offers a nifty shortcut that can quickly reveal whether a global search and replace operation would be safe. Type the search term in the “Find what” field. Then select the option “Highlight all items found in”, immediately below this field, and use the dropdown menu to specify where Word should search for that term (e.g., the main document, headers and footers, comments). Clicking the “Find All” button will highlight all matches in the text in a single step.”

The differences between the PC and the Mac are clear and helpful and are not disruptive. He also covered other software, which makes the book more valuable, especially if you are working with clients who have older or less conventional systems.

Overall, he had good discussions of various editing techniques and especially of Internet resources: how to find them, how to use them, and how to establish the credibility of the source. For example, on page 410:

“As a general rule, give precedence to sites with clear and rigorous editorial policies for controlling the quality of their data.”

In particular, I was pleased to find excellent suggestions for editing less common files, including databases and spreadsheets, as well as Web pages, ASCII, and RTF files. The information also covers editing different tagging languages such as SGML and SML. For example, on page 336:

“The key to opening our horizons wide is the following: most applications, in addition to saving files in their own proprietary format, can also save their files in a range of other formats.”

One of the most important chapters was on the need to save and back up work regularly, as well as make external copies. This chapter also included valuable information on confidentiality, for the client as well as for you.

I do have a few minor criticisms. Three chapters seemed out of place. Chapter 3 is about client relationships, not directly with onscreen editing. It’s important, but I would have made it an appendix. Chapter 13 is about Internet resources. Again, this material is important, but it is not directly part of the onscreen editing process. I would have put it either after the safeguard information or in the appendix portion. Chapter 15 concerns information on backups, upgrades, confidentiality. This information is important information, but it is placed between two chapters directly addressing onscreen editing. I would have made this the last chapter before the two chapters on how to get started with onscreen editing.

I struggled a little with the overuse of long sentences with semicolons. The sentences were all grammatically correct (although I object to the use of “then” as a conjunction). But I found that the long sentences were harder to read, and I frequently had to go back to reread the second clause to make sure that I understood the point.

But these criticisms do not take away from the value of the book. None of the information is extraneous. It is written to editors (and managers) by an experienced editor who has clearly drawn together all the pieces of the work environment that we face daily. He has explained how to make our work easier and more valuable, and has given us a lifeline in a field in which we all sometimes feel we are flailing alone and in the dark. Thank you, Geoff.

Posted on

Alrighty Then

Danica Rhoades

Sometimes editors need to vent. They need to get a little validation for their feelings. They need to know the crazed need-to-scribble-all-over-a-document-before-shredding-it sensations that soar through their weary minds and bodies when they see the same “wrong” writing repeatedly are normal (sort of)! Luckily, the Technical Editing SIG’s discussion board gives editors the opportunity to do just that.

Recently, a frustrated member provided the following example and question:

“Do procedure A, then do procedure B.

Anyone want to guess what it is about this structure that is driving me nuts?”

The language-savvy members of the SIG were quick to identify the issue: the use of “then” as a conjunction.

While the issue wasn’t tough for the group to pick out, it was somewhat more challenging for them to identify how to deal with it (if in fact it needs to be dealt with). In all, the responses fell into three categories (each assigned a pop-culture title used as a heading below):

  1. Alrighty Then: “Then” as a conjunction is okay, even necessary, in some circumstances.
  2. Then There Were None: “Then” should never be used as a conjunction.
  3. And Then: “Then” should follow “and” to eliminate the issue.

 

Alrighty Then

Multiple discussion participants noted that they use “then” as a conjunction when the second sentence is short.

That said, with procedural writing, there was division among the group.

One member noted a preference for using parallel construction with numbered or bulleted statements, such as this example:

  1. Open the folder.
  2. Copy the contents.
  3. Paste the files into a new location.

Another member argued that the absence of compound statements could change the meaning in a procedural document, such as with these examples:

  1. Remove the four screws securing the print engine to the applicator and then remove the print engine from the applicator.

OR

  1. Remove the four screws securing the print engine to the applicator.
  2. Remove the print engine from the applicator.

This member noted that when the fourth screw is removed, the user needs to have something supporting the print engine or it will crash down, damaging the user and/or the print engine.

Then There Were None

Grammatically speaking, “then” is an adverb, a noun, or an adjective.

Another reason cited for not using “then” as a conjunction was that it hinders readability/comprehension. There can be nuances in meaning in certain contexts or environments. Editors who know their audiences well might elect to use “then” in this manner, but this often slows comprehension.

And Then

The supporters of the “and then” construction share the previously mentioned notion that compound ideas are sometimes necessary. For example, simple steps are often combined in prose in this fashion:

“Open the document, and then click File > Save As.”

A related problem was also identified; using “and” to connect to elements that are not simultaneous:

“Type the file name and click OK.”

Some international readers and translation software read this sentence to mean:

“Type the file name while you click OK.”

The “and then” facet of the group noted the most common way to deal with both the “and” and “then” issues is to use “and then”:

“Type the file name, and then click OK.”

Other Issues to Consider

Regardless of your personal stance on whether “then” is acceptable as a conjunction, there are additional issues that can complicate the situation. For instance: documents that are translated. The irregular use of “then” can create issues for the person translating and for the users of that document. In other situations, “then” can lend ambiguity if there is no “if” preceding the “then.”

Overall, the general sense was that it is most important for the editors to understand their audiences’ understanding and needs. Many documents work well with less-formal language, while others could cause injury or result in broken products if the language is not extremely clear and precise.