Archive for the ‘Technical writing’ Category

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

Using Zoom to record a presentation with no audience

July 27, 2020

With conferences off my agenda for the next year or two, or more, as a result of COVID-19 I’m considering doing some pre-recorded webinars based on conference presentations I’ve done over the past few years. Time zone issues mean that presenting live to anywhere outside Australasia or east Asian countries is out of the question.

But first I needed to get a webcam for my computer (my laptop’s inbuilt webcam is very grey and grainy). Do you know how rare webcams became as everyone started working from home? My first purchase was a disaster (a $100 no-name one from Amazon, which overexposed everything no matter what light I used, and didn’t sync my moving lips with the sound it recorded; to their credit Amazon refunded me in full). My second purchase from a local retailer this past weekend (stocks are now returning to retailers) was more successful, and I now have a Logitech C270, which seems perfect for webinars as it doesn’t have a wide field of view and seems to focus more on your head and not everything else in the room. The light balance without using their software, which you have to download separately from the Logitech website, is good and so far I haven’t needed to install that software. The microphone seems to pick up voice well too, and there’s no time lag between my voice and my moving lips. I’ve only tested it with the Camera software that comes with Windows 10, and with Zoom.

Zoom will likely be my preference for recording any webinars I might do as it has screen sharing functions I’m familiar with from webinars I’ve presented that were hosted by professional organisations in Canada and New Zealand. But I’ve never hosted my own, nor have I tried to record myself presenting a webinar without an audience. It wasn’t easy to find out how to, using Zoom’s own help, but I found an excellent set of instructions from the University of Oklahoma that got me started: http://www.ou.edu/cas-online/website/documents/Using%20Zoom%20to%20Record%20Presentations.pdf (I’ve put a copy of that PDF here Using Zoom to Record Presentations in case it disappears from the university’s website).

My first tests using those instructions worked well and I was able to record successfully.

Next step is to figure out how to show me as the active speaker (typically at the beginning and end to simulate a conference presentation) then switch to the PowerPoint slides and back again. Zoom has an option in the settings (Record settings) to display a small view of you presenting, or not, but I want to start off with a full face intro, and then switch to that thumbnail view while the slides take over. Back to the learning curve! I’ll update this post as I discover things. Of course, if someone already knows how to do this, feel free to comment!

Update 28 July 2020: I did a bit more testing with various settings and discovered these seemed to work best for my setup:

  • Wear the headset when recording and use the headset’s microphone as it’s clearer than the webcam’s mike (NOTE: I haven’t yet installed the Logitech webcam’s software, so I’m not sure if that will make a difference or not)
  • Zoom settings > Video: Touch up my appearance (I left the rest as the defaults)
  • Zoom settings > Share Screen: Side-by-side mode (rest were the defaults)
  • Zoom settings > Recording: Record video during screen sharing AND Place video next to the shared screen in the recording (rest were the defaults)
  • When you go to Shared Screen mode in the Zoom recording, resize the thumbnail to the maximum allowed, otherwise you’ll look like a small dot in the recording
  • PowerPoint > Slide Show tab > Set Up Slide Show: set the Show Type to Presentation by a speaker (full screen)

Switching from me as the active speaker to the shared screen and back again doesn’t appear to be very intuitive, and I couldn’t find a setting in Zoom to do this seamlessly. The only way I could do it is described in Steps 6 to 12 of the instructions below:

  1. Start PowerPoint and switch to presentation mode.
  2. Start Zoom and start a new meeting.
  3. If muted/turned off, unmute the audio and turn on the video in Zoom.
  4. Optional: Put on your headset if you’re going to use that microphone, then click the arrow next to Mute and select the headset’s microphone.
  5. Adjust the webcam to get your face in the viewport as you want.
  6. Ready? Click More (the three dots) in the Zoom controls and select Record on this computer.
  7. Start speaking and introduce your presentation. Where possible, speak to the webcam lens not the screen to be more personal to your audience. (Tip: Some people suggest putting a cutout of a friend’s picture next to the webcam and using that as your ‘audience’).
  8. Click Share Screen.
  9. Choose the screen to share (i.e. the full screen of the PowerPoint presentation). This puts the video of your face into a thumbnail view at the top right of the viewport being recorded.
  10. Optional: Resize the thumbnail to maximum size.
  11. Do the presentation.
  12. To return to the video of your face, click Stop Share to stop sharing the screen.
  13. Finalise what you have to say in the presentation, thank the attendees, then click End.
  14. Once you’ve clicked End, click End Meeting for All.
  15. Zoom will automatically create an MP4 file of the recording.
  16. Before distributing/publishing it, watch it and check for places that you may need to re-record. (I don’t know how to cut and splice changes into a video like this, but there will be software that does this. If it’s only a minor error, don’t fuss too much about it—it will show you’re human and that you make mistakes like everybody else. If you were on stage doing this presentation, you might make mistakes there too, and nobody would think less of you for it. Only re-record if there are major errors you want to correct, such as things not working as they should (practice several times beforehand), clothing that disappears into the background, background objects looking as though they are growing out of your head, family members or pets interrupting you, exceptionally loud noises coming from outside that you have no control over, etc. If this is a solo presentation for later distribution, then re-recording is not as disastrous as if it was a live presentation where these things went wrong.)

See also: 4-minute YouTube video of recording yourself in the presentation: https://www.youtube.com/watch?v=gk7l1FJB35s

[Links last checked February 2021]

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).

h1

Catching potentially expensive errors of fact

June 30, 2019

How much does an editor really save a company compared to how much you pay them? Here’s a recent example…

I edit a lot of documents written by those in companies associated with the heavily regulated Australian oil and gas industry. Many are environmental management plans or safety case documents that must be approved by state and/or federal regulatory bodies before a multi-billion dollar project (e.g. a new drilling platform, pipeline, or processing plant) can go ahead. So getting these approval documents right the first time is important—it costs a LOT of money if the approvals process is held up because of errors in the documents. Errors mean they have to go through another round of corrections, technical, editorial, and legal review, and submissions, and this can take months—in this industry, months of delays equals a LOT of money.

Which is why the small thing I caught the other day could have had very expensive implications (both in cost and reputation) for the Big Company who had contracted out the document to the Specialist Company I was working for.

The document detailed the Big Company’s compliance with a piece of federal legislation and a program that resulted from that legislation (I expect these paragraphs were copy/pasted from a similar document written by Big Company some years ago). I wasn’t familiar with the Act, so I checked for its correct wording and date, as well as the official name of the program—I believe that this is part of my job as an editor. Imagine my surprise when I clicked on the federal government link to find out the Act (and the program) were repealed five years’ ago! And neither was replaced with anything else, which meant that all Big Company’s statements about how they were complying with the Act were now called into question. I flagged it in a comment to the author (adding links for them to verify what I found), and made sure I included that information in my final email to my contact at the Specialist Company when I sent the edited document back. She was stunned and very grateful to me for picking it up—none of the authors had.

Now, because all these documents go through Big Company’s legal department before submission, you might wonder why it wasn’t picked up by them. Well, what tends to happen is that the Specialist Company writes the document (often based on previous documents supplied by Big Company), I edit it for the Specialist Company, then when it’s all OK from their end, they give it to Big Company, who then have their technical specialists and lawyers review it before it gets submitted to the federal/state regulators for approval. Yes, it’s likely that Big Company’s legal department would have picked it up, but that would have then cast doubt on the reputation of the Specialist Company. And had it slipped through that final check, someone in the regulators’ offices would have picked it up—after all, they need to know the relevant Acts and compliance stuff backwards—which meant it would have been sent back and the approvals process started again.

So what sort of costs did my fact checking potentially save? Here are some:

  • financial costs of the document going through further rounds of reviews (costs borne by Big Company, Specialist Company, and regulators)
  • time costs of the approval being delayed because of further rounds of reviews (time costs borne by Big Company, Specialist Company, and regulators)
  • reputation costs for Big Company in the eyes of the regulators
  • reputation costs for Specialist Company in the eyes of Big Company (with potential loss of current and future contracts as a result)
  • if the compliance program is still operating despite the Act being repealed, then the costs Big Company pays and has paid over the past five years for compliance audits, meetings, travel to (remote) site, accommodation and meals at site, etc.

If you think an editor’s rates seem high, then consider the cost of NOT getting such a document edited. In the scheme of things, my fee was a drop in a very large ocean, yet could have potentially saved hundreds of thousands—if not millions—of dollars.

[This post was republished on the ACES blog, 25 November 2019: https://aceseditors.org/news/2019/catching-potentially-expensive-errors-of-fact]