Archive for the ‘Editing’ Category

h1

Do I need a style guide?

October 17, 2021

A client recently asked me if they should have a corporate style guide and whether I could help them with that. They’re a small consulting company, with probably fewer than 30 employees. They write a LOT of reports.

Below is a summary of my response to them.

**********

I strongly recommend that every company of more than a few people has an in-house style guide, especially if they’re doing a lot of writing. Plus a standard dictionary they use for general terms, and possibly a specialist dictionary for terms used in their industry. Together, these save you from answering questions all the time about whether certain terms are hyphenated or capped, whether to use indents (not for business writing), double spaces (never!), etc. The ‘I’ve always done it like this because my Year 5 teacher told me so’ method of writing for corporate reports etc. is NOT a valid style guide. Times change, language changes, and there’s a good chance the Year 5 teacher got the ‘rule’ from their Year 5 teacher, who got the rule from their Year 5 teacher and so on.

Most in-house style guides are based on an official published style guide, either for the industry, a professional body, or for a publication (e.g. in the US, they mainly use the Chicago Manual of Style or AP for general works). Most style guides will list the dictionary that they base spellings, hyphenation etc. on. In Australia, that’s typically the Macquarie Dictionary, and I would suggest that you take out an annual online subscription to it—it’s pretty cheap, and you don’t have to have the very weighty tome on your desks. I use my Macquarie subscription EVERY day; if it was the hard copy, I’d rarely open it. (https://www.macquariedictionary.com.au/shop/home/?category_selection=True#subscriptions)

In Australia, we have the Australian (government) Style Manual (ASM) that many corporate/industry/professional style guides are based on—it’s available for free online and was recently (2020) updated from the previous printed edition (2002): https://www.stylemanual.gov.au/. There’s also AMOS https://stylemanual.com.au/contents/introduction-amos, which focuses mainly on scientific writing (I’m not a subscriber to AMOS so I don’t know much more about it). AMOS helpfully lists where their guide differs from the ASM: https://stylemanual.com.au/sites/default/files/amos-quickguides-dta_vs_amos-0122dec20.pdf

I’ve created a style guide for [name of corporation]’s health, safety, and environment documents (not shared for client confidentiality reasons). For other clients, I use their in-house style guide for the documents I edit for them. In addition, for some clients I also create a style sheet to go with their edited document that details the choices I made for THAT document that aren’t covered by the style guide. NOTE: A style sheet is specific to a SINGLE document, whereas a style guide applies to ALL documents produced (for example, the style guide might say no apostrophes in geographic names and give a couple of examples, but the style sheet might list all the geographic names used in that document).

It takes a while (several months on and off) to develop a style guide and there’s a lot of back and forth between those involved to nut out and come to agreement on what ‘rules’ you want to enforce (remember, there are no real rules, just traditions and conventions—it’s a guide, not something set in stone). There should only be ONE point of contact in the company for whoever develops your style guide. That contact person discusses style guide issues in meetings with others in the company and relays the decisions back to the person developing the style guide. Be warned—discussions can get HEATED!* (yes, I’ve been there, done that!) And you’ll be surprised how passionate some people are about commas, dashes, and semicolons! And spaces… (all those rules from the various Year 5 teachers over various generations and education systems will come spilling out).

You also need to decide whether you want your style guide to be fully searchable online (as per the ASM), or a printed guide (e.g. PDF) available online. If fully online, that adds another (expensive) layer to the mix as the website for it has to have full text search capabilities and a navigable table of contents.

So, short answer – yes, I can help you develop a style guide, but you have to do a lot of groundwork at your end before you start thinking about producing a document. You need to decide:

  • what has to go in it (I’d recommend only variations from the standard ASM, for example; for scope, use the table of contents from the examples I’ve attached as a guide [not attached to this blog post, of course])
  • what your corporate (not personal) decision is on all these things, then start noting those decisions for whoever prepares your style guide.

Once you send your notes and decisions to whoever is developing the style guide, they’ll come back to with lots of ‘what about?’ scenarios that you’ll need to make further decisions on. You can save yourself a lot of time and therefore money by sticking to a standard style guide and ONLY using a in-house guide for exceptions/variations or to summarise what’s in the standard style guide.

***********

Further to this, many style guides, especially those from professional bodies, may include a list of terms and how to write them. In mining/resources/geology, do you write ‘down hole’, ‘down-hole’, or downhole’, and does the word form vary depending on whether you’re using the term as an adjective or a noun? (for an example of a terms list like this, see p50 onwards of the Society of Petroleum Engineers Style Guide: https://www.spe.org/authors/docs/SPE_Style_Guide_2019.pdf). Having a list like this in a style guide, or as an appendix to it, saves a LOT of time for those who are doing the writing, whether they are experienced writers, or just new to the company or industry.

* Some 15 years ago I was working as a technical writer for a software company. They had several programs that they’d developed and were about to start marketing, but there was NO consistency in how they named one particular program. Let’s call it ‘Jet Forms’ — was it ‘Jet Forms’, ‘JetForms’, ‘Jetforms’, ‘Jet-forms’, ‘Jet-Forms’, ‘jetForms’, or any other variation on this? Between the marketing people and the developers and the website content people, I saw almost every variation you could imagine for just this one product name! I raised the inconsistency in a meeting as I had to document this product and thus use the name hundreds of times, and said we HAD to make a firm decision on what to call it so that EVERYONE used the same term to avoid confusing our customers. We had 8 people in that meeting (2 of whom were the owners of the company), and I couldn’t believe they spent an hour discussing it! It cost the company 8 hours of wages while we haggled over a single word. And no, some 15 years on, I can’t recall what they decided, but I certainly recall the long discussion that was a waste of time and money when just one of the owners should have said, ‘It’s xxx’, and we’d have been done.

h1

Best. Unsolicited. Testimonial. Ever

October 11, 2021

One of my geology clients wrote a LinkedIn article that both praised me enthusiastically AND promoted the use of editors (October 2021). The article is here: What to do when the write right words won’t come out, and a PDF of it is saved here.

Two other clients also added their praises for my work in their comments for that LinkedIn article; my client had referred me to both of them in the past year:

  • We worked with Rhonda Bracey on a major project in the past year and had a fabulous experience – we all agreed that having a professional editor was worth the additional cost. (JL, Canada, minerals exploration company)
  • Rhonda is a godsend Jun! I’m so grateful you put me onto her! This article is great; shows everyone they CAN share their ideas and contribute to our science, even if they lack the confidence in writing to do so – they just need to source the right help! Love it (MH, Perth, structural geologist)

Yes, I blushed! But I think I might be able to put that imposter syndrome to bed now.

h1

List of tasks done by technical editors

June 19, 2021

One of this blog’s readers alerted me to this list of tasks that technical editors do, written in late 2020 by Yoel Strimling: http://stc-techedit.org/corrigo/how-do-you-want-that-edited/. Not all technical editors will do all tasks, and no doubt some could add other tasks, but I thought this list gave a concise overview of the tasks we undertake when editing a piece of technical writing, along with approximate times for each stage.

In the same vein, I have a ‘triage list’ of editing tasks that I can do for clients—I ask new clients or those who have a limited budget and/or timeframe to use this to direct me as to the highest priority things they want done to their document: https://cybertext.com.au/editing_levels.html As a perfectionist, my tendency is to do it all, but if you’ve only given me xx hours to edit a nnn-page technical document, then you need to be prepared to tell me what to focus on, because I’m not a superhero.

[Links last checked June 2021]

h1

Harmful language

May 3, 2021

This Tweet from Crystal Shelley (@redpenrabbit) resonated with me:

When editors speak up about harmful language, we give writers the information and power to make a decision: change the writing or leave it as is.

When we’re silent, it harms writers and readers. We take away that choice and guarantee that the harmful writing stays.

 

h1

Good article on the differences between line and copy editing

January 12, 2021

Based on the definitions Jane Friedman uses in her article (https://www.janefriedman.com/the-differences-between-line-editing-copy-editing-and-proofreading/), my editing involves a blend of line and copy editing, with some Word formatting magic thrown in, if required by the client. I don’t do proofreading, developmental editing, or substantive editing. NOTE: Her examples include some from fiction, whereas I only edit factual materials (typically corporate/business/government reports and other written communication). And she uses CMOS as her main style guide, whereas I use the Australian Government Style Manual for works for an Australian audience (https://www.stylemanual.gov.au/).

The list of the things I include in an edit vary according to what the client wants—I offer clients my ‘triage list’ of editing tasks from which they can choose: https://cybertext.com.au/editing_levels.html

[Links last checked January 2021]

 

 

 

h1

Definition of technical editing

December 30, 2020

An editing colleague posted a link to an article by Tom Lang on technical editing and the tasks and thought processes involved, with some excellent examples: https://ese.arphahub.com/article/53691/

In the article, he cited a thesis by Natalie Peterson that lists some 410 (!) technical editing tasks. So I went hunting down rabbit holes for the thesis, and finally found it. Not only does it list and categorise those 410 editing tasks (in Appendices 1 and 2), but Peterson also offers a new definition of technical editing that resonated with me:

Technical editing is the suggestion of improvements to a document or other communication product to help an author increase the effectiveness and efficiency of the transmission of information in a specialized subject to the author’s intended audience.

(Peterson, Natalie L, Revising Theory: A Universal Framework for the Comprehensive Editing of Technical Communications, 2017, Masters Thesis, University of Wisconsin-Stout; available from: http://www2.uwstout.edu/content/lib/thesis/2017/2017petersonn.pdf)

h1

What an editor does

September 29, 2020

Spotted in a Facebook editors’ group, with no attribution, unfortunately. Thanks to the person who put this together. My daily work life is definitely the bottom right image!

What my friends think I do: image of Words with Friends game; What my Mom things I do: image of a person with glasses in business attire marking up a piece of paper they're holding; What writers think I do: image of an angry person ripping up paper; What society thinks I do: image of a McDonalds 'Drive Thru' sign changed to 'Drive Through'; What I really do: image of a heavily marked up Word document with track changes and comments visible

 

h1

Australian Style Manual update

August 1, 2020

The Australian Style Manual (ASM) was last published in 2002. There have been pushes to get it updated for a long time, and finally, it’s been done. Although it was written for government writing at all levels, the reality is that it’s been the only ‘official’ style manual in Australia and is used by Australian editors, especially for nonfiction writing.

The ASM (and Macquarie Dictionary) are the foundations for the style decisions I make when editing writing written by my Australian clients (as with any style guide, I base my decisions on the ASM, and have exceptions where the client’s preference conflicts with that in the ASM, or where the ASM doesn’t cover the issue).

You can find the free beta version here: https://www.stylemanual.gov.au/ (By the way, Macquarie Dictionary online is available for an annual subs of ~$40; they’ve just released their latest print edition [8th], but with 2 hefty volumes, I’ll pass! https://www.macquariedictionary.com.au/)

I haven’t gone through the online ASM extensively, but I’ve noticed a couple of things related to numerals:

  • all numbers 2 and above should be written as numerals (no more ‘if it’s under ten, write it out in full’)
  • thousands should now be written with comma separators (the previous ASM said to have no punctuation for 1000-9999, and a nonbreaking space as separator for 5 numerals and above; e.g. was 4567 and 25 678 943 – now 4,567 and 25,678,943)

I don’t know when the ASM will be released as a final version or whether they’ll charge as subscription fee for it, but I’ll likely start following its guidelines over the next few months as I become familiar with it.

h1

And my work here is done!

December 11, 2019

One of the environmental scientist authors I work with emailed me this earlier this week:

I’m reading the book ‘Sapiens’. It is written by a scientist and littered with ‘in order to’. Great book but I feel like putting a pen through the unnecessary words. You’ve ruined it for me :-)

My work here is done!

h1

Lessons learned from a corporate report

November 30, 2019

I recently did a few editing passes on a 640+ page environmental report that was to be submitted to a federal regulatory authority. I wasn’t able to fully edit the report, but I was able to tame the formatting issues in Word (including making sure all tables had a similar look), check for inconsistencies in common terms and phrases, fix the cross-references to other sections/figures/tables/appendices, check the abbreviations/acronyms list reflected the abbreviations used in the document, ensure nonbreaking spaces were used between values and units of measure, etc. There was no corporate template or style guide to use (the company is very young), though someone had put a very basic template together—cover page, headers/footers and the like—but hadn’t set up styles, therefore the formatting of bullets, numbers, body text etc. was all over the place. Multiple authors had worked on this report, and each had done something a little different with their formatting, and varied in the terms they used and whether they capitalised or hyphenated them or not.

After I returned the document to my contact, she asked if there were some ‘lessons learned’ that she could share with her boss and others involved in the document. Here’s a summary of the email I wrote to her:

  1. Template: Get a corporate report template in place, with as many necessary styles in it and sample tables set up ready to be copy/pasted and modified. Learn how to use it and WHY you should use it.
  2. Style guide/sheet: In the absence of a full style guide, set up a corporate style sheet that lists the preferred ways of spelling/using terms (e.g. the correct spellings/hyphenations for place names, words that can trip you up – e.g. wellhead/well-head/well head, tophole/top-hole/top hole). Make your authors use it, and that you forward it to whoever edits your docs so that they can follow the decisions already made.
  3. Styles:
    • Discourage writers from using the buttons on the Word toolbar for bullets and numbers (there be dragons!) – use the relevant List Bullet and List Number styles
    • Learn how to apply styles to new text, and how to paste text from another doc and format it correctly (NEVER copy across section breaks, for example – more dragons lie there!)
    • Learn how to apply table formatting/styles – for example, in the [company] doc there’s a special button on the Table Tools > Design tab for applying the green table, but I wonder how many know how to use it and instead spend ages setting up the borders, shading etc. manually.
  4. Clickable cross-references (x-refs):
    • In the absence of a program like EndNote, learn how to do x-ref numbered citations so you don’t end up with [CorporateAuthor] 2019a, 2019b, 2019c etc. This sort of citation is a nightmare to update
    • Learn how to assign x-refs (clickable links are recommended for anything that’s going to be PDF’d and read on screen).
  5. References: Make sure authors are CONSISTENT in doing references, specifically when to apply italics, what punctuation to use, how to indicate when a URL was valid etc. (a style guide would help here). I didn’t check any for accuracy, but verifying references online is a BIG job to do after the fact—far easier for the author to grab ALL the citation details when they are writing the doc.
  6. Terms: Make sure authors are pedantic about adding initialisms/acronyms/abbrevs, units of measure etc. to the relevant terms lists—it’s easier to check if something is there or not than to create the list from scratch after writing the doc. I use software macros that can pull out some of this, but not all.
  7. Unlearn/break bad habits that work for university but not for business/corporate writing. Think like a business person with limited time and NOT like a uni researcher! The habit of writing to a word or page count has been ingrained since about Year 5 and reinforced all the way through to doctorates and, later, journal and other publications. Business reports need to be succinct, use plain language, and get to the point in as few words as possible, without losing meaning. Some examples of bad habits:
  8. Learn new habits: e.g. keyboard shortcuts for things like nonbreaking spaces (Ctrl+Shift+<spacebar>), turn on/off track changes (Ctrl+Shift+e), add a comment (Ctrl+Shift+m), change case (Shift+F3).

I also mentioned and linked to presentations I’ve given to government departments, editors groups, and conferences on plain language writing and on working more efficiently with Microsoft Word (http://cybertext.com.au/presentations.html).