Posts

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.

Posted on

General Impressions: “In Praise of Editors”

Last month, on Salon.com, Gary Kamiya wrote a very interesting article titled “Let us now praise editors,” which you can read here: http://www.salon.com/opinion/kamiya/2007/07/24/editing(external link). Janice Gelb sent this article to our discussion list, quoting a few passages from it, and I was surprised that we did not start any discussions around it.

As I finished the article, I was left with a series of questions that I thought we might enjoy discussing. Please feel free to write a comment here to our blog, but please also subscribe to our discussion list, and see what gets going over there.

Here are the questions that this article raised for me:

  • Are editors less confident than writers? Kamiya said that “a good editor needs to be as self-confident as a writer” (mainly because we are dealing in a subjective realm of trying to improve the writing for the reader).
  • Is writing harder than editing? Kamiya said that writing is very creative, whereas editing is reactive. Initially, I agreed with that statement, but upon reflection I’m not so sure.
  • Are editors an endangered species, especially with online and Internet publishing? I’d like to think that those writers, those businesses, those publishers who value high quality writing for their readers will not allow us to go the way of the dodo bird. Kamiya stated: “The art of editing is running against the cultural tide. We are in an age of volume; editing is about refinement. It’s about getting deeper into a piece, its ideas, its structure, its language.” This was one of the few places in the article that Kamiya acknowledged that editing is more than just grammar and style, but it was appropriately located.

Kamiya ends his article by truly singing the praises of editors and suggests, “Someone is noticing. Someone is reading. Someone cares.” I sure hope he is right. What do you think? Is someone noticing?

Posted on

Excerpts from STC Annual Conference Report

Kelly Schrank

[Note: I wrote a very detailed 14-page conference report for my employer. I then abstracted that report and published a 5-page article in Newsbrief(external link), the Mid-South Chapter’s newsletter. What appears here is a belated collection of highlights from that newsletter article.]
The Technical Communication Summit, STC’s 54th Annual Conference, was held May 12–16, 2007, in Minneapolis, Minnesota. Around 1,400 people attended the annual STC conference this year.

[…]

My first session was “Estimating and Tracking Project Costs for Financial Success” with Joyce E. Lasecke. I thought this was a good session, very structured with good handouts that make it easy to go back through later and re-learn the concepts. Her presentation had two distinct parts: how to estimate and how to track. She very methodically began the part on how to estimate by outlining the three ingredients to a project estimate: (1) metrics, (2) assumptions, and (3) risk assessments. She then defined those and showed how to use them to your advantage. She went over the case study provided, which seemed to me to be a good example of a project estimate. The part on tracking was also good, with insights for how to start and what to do when you get off track. A good session, especially if project management is part of your job.

My second session was “Effective Page Layout for the Non-Artist” with Jean-Luc Doumont. Jean-Luc was an excellent presenter, very organized and very entertaining. He believes that page layout is about revealing the structure of the document visually. Unlike some people who think that a pretty layout and fancy graphics will bring the reader’s attention to the text, he believes that people will pay attention to the graphics and ignore the text. He also characterized a page as having two dimensions: vertical and horizontal. He believes documents need much more white space than most people allow. He likes big top margins and big left margins. “Space is a luxury.” This is where it became obvious to me that his ideas on design could be a bit “creative” for most technical communicators. His examples are full of white space and seem (to me) to be much more the work of marketing than documentation though I liked the look of them. All in all, an informative and fun session with lots of takeaway ideas.

[…]

My fourth session was “If I’d Known Then What I Know Now – Lessons Learned and Best Practices.” This was a lively and informative panel of speakers. Each discussed a lesson learned in their career and a trend in the technical communication industry. One of the funniest things to come out of this panel (from Bobo Vatovec): “The most common language in the world is Bad English”. A lot of their lessons learned and trend advice was tough to swallow: technical editors being told to lower their level of quality, tech writers being told to spread their wings and move away from our tech pubs departments? But these are experienced technical communicators doing a variety of different things in the industry for big companies and their own companies, so we should at least listen to what they have to say…

My fifth session was “Copymarking, Clarity, and More: Progressions of STC’s Technical Editing Community.” I went to three different tables to learn about three different topics:

  1. The first was “Growing and Managing a Formal Editing Process” with Lisa Adair. Lisa is a technical editor for Rockwell Automation, a company that is revamping their whole tech pubs process. Their new system is topic-oriented, not publication-oriented; writers own a section of information, as opposed to documents. Their formal editing process began with a task force that worked on updating the company style guide. They began by picking a secondary style guide, and put topics in the company style guide where the editors veered from the secondary style guide or where the secondary style guide didn’t address something specific to their company. Another instrumental part of their formal editing process was to establish the levels of edit and create an editor’s checklist. The metrics they created in the level of edits document allow them to quantify their job. This was an interesting session for those in big companies that may have many editors, but it emphasized to me the need for an editor’s checklist and to be estimating my work.
  2. The second was “Make Every Technical Editing Minute Count” with Jackie Eldridge. Jackie is a very experienced editor who put together a thorough and helpful handout for this progression. To understand the project, she suggested you first find out the purpose of the document from the author. Make sure the introduction material covers this, and that steps are in a logical sequence to that end. To understand the author’s expectation of you, she suggested that you use your editing checklist as a menu: talk to the author about which of these are most important to them. Advantages to knowing the author include being able to look for their trouble spots and fixing those so they do not embarrass them. Generic editing advice included: looking for the three “in”s: inconsistencies, inaccuracies, and incompleteness; making sure there is a source for information presented; and using different colors for different types of edits. I found this session helpful in not only proving what I already know to be correct, but also in offering some different ways of thinking about the process.
  3. The third was “Concision and Clarity” with Susan Ledford. Susan is a technical writer and editor with experience in localization issues. She offered four reasons to pursue word reduction: (1) decreases costs, (2) increases readability, (3) increases usability, and (4) supports re-usability and single sourcing. In localization, word reduction is a directly measurable reduction in costs, as those excess words don’t have to be translated. For publications that are printed, shorter documents cost less to print. In addition, there is less to maintain when you reduce documentation length. In single-sourcing situations, the difference is exponential. From a usability standpoint, if there is less to read, readers are more likely to read it. She advises to do the following: (1) Use the search function to help you delete worthless words, (2) Create checklists of the type of words to commonly reduce, and (3) Rephrase sentences and paragraphs and reduce them to “content chunks.”
[…]

My eighth session was “Out of the Solitudes: Progressions of STC’s Lone Writer Community.” I went to three different tables to learn and talk about three different topics:

  1. The first was “Preserving Sanity as a Lone Writer” with Dana F. Utz. The sole writer in his department for the last 8 years, Dana believes you should impose structure on your work through a “styles and standards guide.” He also suggests acting as if you are a part of a department in how you approach your work by documenting your tasks in a policies and procedures guide and tracking project time and milestones. He had a very nice handout of the presentation.
  2. The second was “Editing Your Own Work” with Jerry D. Franklin. As a freelance high-tech marketing copywriter, Jerry must edit his own work on a regular basis. He offers six suggestions for editing your own work: (1) Take time away from the project to gain your objectivity (distance), (2) Put on your proofreader persona, (3) Use other style guides, (4) Create a style guide and document templates in advance, (5) Get non-SME reviewers on your team (customer service, tech support, marketing), (6) See if you can get a student to proof for the experience.
  3. The third was “No Longer Alone” with Christopher Thiessen. Chris was an engaging speaker, very much interested in our own experiences and having us share them. He offered advice for people with specific questions and concerns. Like many of the other editing speakers, he suggested creating a style guide to ease the transition from working alone to working with others, and he suggested creating a list of commonly used words and their preferred usage.

 

[…]

The conference materials are available on the website(external link). They are organized by presenter, so if you want the materials for any of the sessions I described, you should have an easy time finding them.