Archive for the ‘Technical writing’ Category


Contrast is essential

April 12, 2023

For many many reasons, including readability, accessibility etc., good contrast is essential for anything you need to read… none of us is getting any younger. Black on white (or vice versa), even dark grey on off-white, is good. But light grey on medium grey is not (I’m looking at you, all the 20-something designers who seem to think that 50 shades of grey is cool for apps, software, and websites. It’s not.).

Similarly for colours—not only do you need to use contrasting colours, but you also need to make sure, where possible, that you are using colours that can be readily distinguished by those with limited vision or some form of colourblindness, and colours that don’t ‘flare’ or clash when you try to read them (e.g. don’t use red text on a green background or vice versa).

In the environmental reports I edit, typically there are several maps. One of my editing tasks is to check the spelling of the place names and any other text on the map, and also to check the legend to make sure that all the colours or symbols used in the legend accurately reflect what’s on the map. Because many of the companies I work for have large GIS departments, the maps are mostly very professional and accurate and it only takes me a minute or two to check them. But sometimes something is wrong and I have to query it.

In a report I worked on recently, they had included many maps. All were made by the same GIS team, and nearly all had reasonable or good contrast in the colours used on the map (as reflected in the legend). For example:

But then there was this:

Even someone with PERFECT vision would have a hard time distinguishing the different areas of this map, as indicated by this legend. And it would likely be impossible for someone who had blue/yellow colourblindness.

I made a note to the author to talk to the GIS people and get them to change this map so it had better colour contrast—there are 16+ million colours they could have chosen from, yet they chose a set of blue/greys and a set of murky yellows that have little to no contrast between them.

(Note: In the document, this legend is MUCH smaller than is shown in this screenshot, making it even harder to differentiate the colours.)



Professional editing standards and ethics

April 11, 2023

Adrienne Montgomerie has pulled together a fantastic resource for editors, in which she summarises the main points that various professional editing associations and organisations and other related bodies make about professional ethics and practices for editors:

She’s gone through the relevant documents and codes of practice etc. from organisations including those below, and extracted the relevant sections, then arrange them under categories. The sources she used included:

  • Editors Canada
  • Chartered Institute of Editing and Proofreading (CIEP; UK)
  • Institute of Professional Editors Limited (IPEd; Australia and NZ)
  • Professional Editors’ Guild (PEG [South Africa])
  • American Copy Editors Society (ACES)
  • Editorial Freelancers Association (EFA)
  • Committee on Publication Ethics (COPE [UK])
  • Canadian Press (CP)
  • Associated Press (AP [USA])
  • American Psychological Association (APA)
  • Chicago Manual of Style (CMOS17)

[Links last checked April 2023]


Some perspective on ChatGPT and others in relation to technical writing

March 6, 2023

Much of this blog post by technical writer and documentation and content specialist Michael Iantosca also applies to editors:

Bottom line: Look for the opportunities to make these technologies work for you.

As he says in his third paragraph: “Change is inevitable, and resistance is futile. Yes, jobs will be eliminated by automation, including large language models – eventually, but the workers who’ll be affected most are those who resist and fail to change and adapt.”


Good examples of the different types of editing

March 3, 2023

Australian editor, AJ Collins, has written an excellent blog post explaining—and showing—the different types of editing that editors do:

Her examples show a page of fiction marked up according to the various editing stages, and are a good way to see the differences in what different types of editing bring to the process.

I only edit non-fiction material, typically corporate and government documents and reports (mostly related to the onshore and offshore resources industry [oil and gas, mining, geology] and soil, water and agriculture reports for a government department), and my expertise crosses that very fuzzy line between line and copy editing. The sorts of things I do with the documents I edit are encompassed, for the most part, in the ‘triage’ list of editing tasks I have listed on my website:, and don’t just cover the text but also formatting, checking lists of terms and citations/references, and other tasks to make a document suitable for its audience.


When the job ad for an editor requires editing

February 16, 2023

In an email notification from LinkedIn today, I saw a job posting for a technical editor for a company I have a small degree of familiarity with because it operates in the same industry sector as my main clients. I’m certainly not interested in a full-time job, especially one in the city (I moved from the city 16 years ago and have been working from my home office ever since). But I wanted to see what they were looking for in their job posting, just for fun. Well, just for fun became an exercise in editing their job ad! Maybe that’s what they’re looking for—someone who can ‘walk the talk’ and tell them that this ad needs an editor and who can suggest ways it could be better. So I did that. I won’t be sending it back to them nor applying for the job, but in the process of editing it for better readability, I also came across a whole lot of phrases that could have hidden meanings.

Below are screenshots of the ad that I copied into Word (hiding any identifying information); the marked-up ad with my tracked changes and comments; and finally, the ‘clean’ edited ad (click an image to view it at full size). After the final screenshot, I offer some comments on the possible hidden messages in this ad, and some general comments, based on my <mumble> decades in various workplaces, including city offices.

Original ad copied from LinkedIn into Word (identifying information hidden)

Marked up ad, showing the changes and comments I made

Clean copy of the edited ad

Some potential hidden messages in the original ad and general comments

  • “could be full time” Well, is it a full-time job or not? Do you even know what you want?
  • “flexible around working hours and location” Flexibility in location is contradicted by the statement that you need to be in Perth or Brisbane, and if you have to be in an office environment, there’s a pretty strong clue that you’ll be working standard office hours, though the flexibility may refer to the different time zones covered by the company’s Australian offices
  • “Supporting and championing quality outcomes and processes” Oh, so you want the editor to be the office’s big bad teacher about grammar and the like? And what does ‘supporting and championing quality outcomes and processes’ even mean?
  • Assisting with other office and consulting support functions during leave periods and as required” Ah, you mean you want me to be the receptionist and the person who cleans up the kitchen and takes meeting minutes, too?
  • “Advanced knowledge of Microsoft Word” How advanced? What do you mean by advanced? Self-assessed ‘advanced’ or by some independent measure? Do you want knowledge of macros, tables, complex documents, mail merge, styles and templates, document automation etc.? Do you even know what you mean by this requirement?
  • General comment about skills: How will the skill and proficiency levels be measured? Are they based on candidates’ self-assessments of their skill levels? Will the company run their own tests? What editing benchmarks will be used? Do they want an IPEd accredited editor?
  • “High level of initiative and internal client service” What does this mean? And what does ‘internal client service’ mean in relation to ‘a high level of initiative’? Or should it be a separate skill?
  • “Experience (7+ years) in working in a professional office environment” What’s so magic about 7 years, assuming you can do the work? Am I totally out of the running if I’ve only worked for 5 years in an office? Aren’t all office environments considered ‘professional’ (in which case this is redundant)? Or is there a hidden message here that you won’t take someone who has, for example, only worked from home, or in a workplace like a school or a mine site? The role doesn’t specify ‘Senior Technical Editor’, yet this requirement of 7+ years is a clear message that they don’t want a person just out of school or university
  • “Professionally presented” Not only does it seem that you can’t work from home (WFH) but this hidden code means you need to wear business attire (formal or casual?) to work every day. For females, who make up the vast majority of editors, this sort of business attire adds up to a LOT of money per year (in addition to business clothes and shoes, both of which must be different each day, there’s the costs of make-up, hair, and nails (possibly), dry cleaning/laundering, and stockings if you wear dresses/skirts (they are expensive and nearly always ladder the first time you put them on, so it’s just money in the bin). Other expenses related to working in an office include parking fees in West Perth, wasted time while commuting, purchased lunches/coffees. Nearly 10 years ago I worked out the ‘cost’ of working in an office in Perth was around $10,000 per year—it’s likely much more now. If you aren’t dealing directly with clients and are sitting at a computer most days, as editors do, shouldn’t you dress comfortably in preference to ‘professionally’, assuming someone can define ‘professionally’?
  • “a good work ethic” In whose eyes? How is this assessed? Does this mean you’ll be asked to regularly work more hours than usual and just have to ‘suck it up’?
  • “contribute to the development of our quality processes” Is the technical editor expected to be involved in things like ISO 9001? If so, that’s an entirely different role and skillset, and a different pay grade. If this is part of the job, then it should be made clear and compensated for appropriately, not hidden behind some weasel words.
  • “excellent facilities” What facilities? Free car parking? Child care? Gym? Lunch and snacks provided? Be specific.
  • “in West Perth” Earlier (and later) in the ad they say Perth or Brisbane, but this line specifically relates to the West Perth office. Does the Brisbane office have a similar office environment? Why is Brisbane not mentioned here? If both locations have a similar environment, then delete ‘in West Perth’ from this bullet point
  • “The opportunity to be part of an employee-owned business” This is code for ‘we won’t pay you much but we can offer you shares in our company and you’ll benefit in the long term’. Nope. Give me my money now—I have bills to pay now, not in some fictitious future time of unicorns and empty promises that litter the highway of broken dreams of companies that go bust. And if you decide to take up this ‘opportunity’, at what point are you allowed to be part of the ownership group of employees? After 1 year, 2 years, 5 years? What commitment is required—time, money, both? And if you leave, what happens to your share of the employee-owned business? Is this another way to stop employees from leaving (which is different from using incentive programs to retain them and their loyalty)?
  • “Please note that candidates need to be based in Perth or Brisbane and be either an Australian Citizen, Permanent Resident or have an existing valid working visa. No other options will be considered.” So, NO working from home? Ever? If ANY job is perfect for WFH for at least most of the time, it’s editing. Yet, that’s not an option. You’d think they’d have learnt after COVID that WFH or a hybrid working model works best for everyone who isn’t engaged directly in client-facing work and who enjoys flexible arrangements.
  • Why is no salary/rate mentioned, not even a range? Why do companies waste people’s time like this??? It’s an expensive exercise for everyone to get through all the steps to gain an interview or even a second interview, only to find out that your salary expectations and theirs are vastly different. Maybe they want YOU to state what you want, which is a nasty trick some companies use to not pay the going rate (assuming they, and you, know it). And with no range listed and with the code of silence that surrounds who makes what in a company, this just smacks of dirty tricks. Maybe you think I’m too cynical, but I’ve seen it happen far too many times.

Words to watch for: ‘the East’, ‘the Far East’ and ‘the Orient’

February 5, 2023

As someone living in Western Australia, terms such as ‘the East’, ‘the Far East’ and ‘the Orient’, have always bothered me, but for years I never knew why—I just had a sense of unease when I saw them. I thought they smacked of colonialism, a Euro-centric view of the world, and an ‘otherness’ (especially when used with ‘exotic’). The older I’ve become, the more I consider these terms offensive because they bunch about 4.5 billion people and about 50+ countries under the one term, as though they are the one place and the one people.

For me, ‘east’ means the eastern states of Australia or New Zealand, and the ‘far east’ is the Americas. Parts of Asia—a HUGE area that extends from Turkey to Japan and covers many countries and just over half the world’s population—are directly north of where I live (e.g. Southeast Asian countries, China, and Japan) and are either in the same time zone as me or very close to it. Some cities in Southeast Asia are closer to me by air than cities in Australia! How can I think of ‘the East’ when the places referred to by that term are to my north?

Discussion about the use of these terms pops up every so often in editors’ groups on Facebook, and today, Gael Spivak (a Canadian editor) shared this article, which explains it all far better than I can:

Bottom line: Avoid using these terms—be specific about which country/countries and people


Another bit of bragging

January 23, 2023

Nearly every piece of editing I do is hidden—it lives behind corporate walls and never goes public. But occasionally one does. This latest one was released recently: (it’s a nearly 30 MB PDF download from that page, which is why I haven’t linked to it directly).

Unlike the one released to the public last December, this one was for a Western Australian government department and is a 360p document on the geology, soils and climate of the wine regions of the south-west of Western Australia. I even cracked a mention in the acknowledgements (also rare—see the first sentence of this post!).

I found it fascinating to edit for several reasons:

  • I grew up in the south-west, and have lived in several of the wine regions discussed: specifically Peel, Geographe, Swan Valley, and Blackwood Valley.
  • I like wine, particularly full-bodied reds, so it was interesting to see what combination of characteristics were the best for growing these types of grapes.
  • When I was a kid, I used to play and ride my bike on the ‘ferruginous nodules and pisoliths’ mentioned. It was nice to know that the gravels that caused such grief to my knees when I skidded off my bike have a name :-) Pisoliths, indeed!

[Link last checked January 2023]


ChatGPT: Some uses for editors

January 21, 2023

After doing a few ChatGPT experiments recently and having a lengthy Zoom discussion yesterday with Adrienne Montgomerie, a freelance Canadian editor, I have some initial thoughts on how editors can use this as another tool in their suite of editing tools. And just like any other tool (e.g. PerfectIt, Editors Toolkit, even Word’s find and replace and spellchecker) the results ChatGPT (and similar AI tools) suggests should be used judiciously and with a human eye and brain involved—keep what fits your purpose and the context, and ignore the rest. And if you don’t want to use it, don’t. Some people eschew looking up dictionaries and adhering to style guides, others refuse to use other automation tools—and that’s fine (there were plenty of people who refused to see any benefit in word processors, and before that the printing presses that replaced pen and ink).

But for those who are interested in how AI tools can help in the editing process, here are some of my suggestions (no particular order) based on just scratching the surface of ChatGPT—no doubt there are more, so feel free to add your suggestions in the comments:

General advice:

  • Phrase your request in various ways—you will get quite different results depending on how you phrase your request, or whether your request is broad or quite specific
  • If what you get the first time doesn’t really work, get it to rephrase in a different way (there’s also a Regenerate Response button you can click to get another variation)
  • Use it as a starting place for ideas when you’re stuck, not as the end point (e.g. if you’re an author writing a report from scratch, you might use it to generate an outline based on the topic—again, you’d use this as a starting point and would need to be aware of what needed to be added or deleted for your circumstances)
  • Try some other tools too (

As with any editing, your human brain is the best tool you have even if you use an AI tool to kick off the process:

  • Be aware of obvious or potential unconscious bias:
    • Who are the people behind the AI tool? What is their demographic? (e.g. are they young, predominantly white, male programmers living in a ‘developed’ world?) You may never know, but be aware that the people behind these tools have their own biases as to what they include or not. For an excellent documentary on bias (in facial recognition software) that reflects the demographic of programmers, watch Coded Bias on Netflix
    • Where have they drawn the information from? (good luck with that!)
    • Is there inherent bias in how the responses are phrased? (e.g. are certain groups ignored, such as women, people of colour, people over or under a certain age, entire regions of the world, people with various disabilities?)
    • Bias could be any one or more of these:
      • Is the response applicable to all, or just those in particular societies/countries/regions/socioeconomic groups?
      • Does the response ignore or discriminate on the basis of race, ethnicity, gender, age, ability/disability, etc.?)
  • Be aware of language limitations—as far as I am aware, ChatGPT only responds to requests in English and various computer programming languages, thus excluding/ignoring much of the world’s population, and there are certain areas (e.g. mathematics)  it has limited knowledge about
  • Be aware of false information—try this: ask it to write a resume for you and check how many things just aren’t true (people who’ve done this have reported that ChatGPT lists the titles of non-existent books they’ve supposedly written!). Don’t trust the information given—verify, fact-check, do what you have to do to confirm the information
  • Be aware of the base date of the information provided—from all reports, ChatGPT’s ‘database’ of information only goes to 2021, so any discoveries etc. after this date are not ‘known’ by the tool
  • Be aware that, at this stage, ChatGPT reportedly doesn’t do internet searches and does NOT cite sources for the information it provides, which means it’s impossible to independently verify its results yourself

For some good summaries of what ChatGPT can and can’t do, check out these resources:

[Links last checked January 2023]


ChatGPT: Writing Word VBA macro code: Another use for editors

January 20, 2023

In a comment on a blog post I wrote about using a macro to globally change certain style names to other style names (, Joseph reported getting an error where a specific style name was not found. He asked if there was a way to avoid this. After looking through more than 100 results for my search term—Word macro line to exclude an unfound style—and finding nothing that was suitable, I decided to try ChatGPT as I’d read that it was pretty good at writing and analysing code. I reworded my request a little the first time, but kept the same Google search term for the second try, which gave me a different result.

In both cases, in less than 20 seconds I had enough to work with! And an explanation for how it worked and what to watch out for.


What I asked: Word VBA macro to ignore a style name it can’t find

How ChatGPT responded: You can use the “On Error Resume Next” statement in your VBA macro to ignore an error that occurs when the macro is unable to find a specific style name. This statement will tell the macro to continue running even if an error is encountered, rather than stopping execution. Here’s an example of how you might use this statement in your macro:

Sub MacroName()
On Error Resume Next
‘Your code to apply the style goes here
Selection.Style = “StyleName”
On Error GoTo 0
End Sub

This will skip the error and continue running the macro if it can’t find the style “StyleName” in the document.
It’s important to note that the “On Error GoTo 0” statement is used to turn off the error handling and return VBA to normal error-handling mode.


What I asked: Word macro line to exclude an unfound style

How ChatGPT responded: You can use the “If-Then” statement in your VBA macro to check if a specific style name exists before attempting to apply it. If the style is not found, the macro can skip that step and continue running without error. Here’s an example of how you might use this statement in your macro:

Sub MacroName()
Dim StyleExists As Boolean

StyleExists = False
For Each s In ActiveDocument.Styles
If s.Name = “StyleName” Then
StyleExists = True
Exit For
End If

If StyleExists = True Then
Selection.Style = “StyleName”
‘Code to handle the missing style
End If
End Sub

This will check if the style “StyleName” exist in the document and if true, it will apply the style to the selected text otherwise it will skip that step and continue running without error.
Note that the above code will check for “StyleName” in the active document, if you want to check for style in different document then you should replace ActiveDocument with the appropriate document name.



ChatGPT is not the only AI writing tool

January 19, 2023

ChatGPT has been receiving a lot of publicity since its public beta launch in November 2022. But using AI (specifically ‘large language models’ [LLMs]) for some writing tasks has been around for a long time.

At least 10—possibly 20—years ago, I heard of machine translation (MT) tools when I was working as a technical writer in the computer software industry. For those having to translate user manuals into multiple languages (as required by the EU etc.), these tools were essential for dealing with the repetitious stuff (translate once, re-use many times). Sure, they had their issues, but over time, and as the ‘machine’ learned more, they got much better. Ideally, in-country human translators were then used for checking and cleaning up, and feeding changes back to the ‘machine’ for it to learn better for next time. As each new version of the software was released, only the new information needed to be translated because the MT tool stored the previous changes and had ‘learnt’ the patterns, thus saving companies millions of dollars in translation costs (with software releases generally being about every year, you can just imagine how much it would cost in time and money for human translators to do EVERY translation into 20 or more languages for EVERY release).

Just to be clear, I’ve never used any of these tools or was ever involved in translation projects, so what little I’ve written here is based on what I learned at tech writing conferences etc.

Because the discussions around ChatGPT have interested me, I’ve taken note of some articles, especially related to how to use ChatGTP as a tool amongst the suite of tools I use for editing. Others have spent plenty of time writing about ‘the sky is falling’ scenarios in schools and universities, and some have written ‘let’s all just take a deep breath and see how this can work for us’ articles to counter them.

One thing I’ve discovered in the past few days is that there are PLENTY of AI tools around, not just ChatGPT, that summarise text and do other other writing and editing tasks. And some of these tools have been around for several years—they just haven’t received the publicity and hype that ChatGPT has. (Update 31 January 2023: This website attempts to list many that are publicly available:

Text summaries provided by AI tools could be used for creating an executive summary of a report, unpacking dense writing, summarising a ‘too long, didn’t read [TLDR] article into the main points for a busy person to read, etc. Some of these tools (plus others) are mentioned and linked to in these articles if you’d like to investigate them further:

And an academic article on LLMs: Dissociating language and thought in large language models: a cognitive perspective
(Kyle Mahowald, Anna A. Ivanova, Idan A. Blank, Nancy Kanwisher, Joshua B. Tenenbaum, Evelina Fedorenko; 16 January 2023):

[Links last checked January 2023]