Archive for the ‘Technical writing’ Category

h1

Thwarted by technology requirements

January 16, 2022

Bottom line 1: Check an app’s operating system requirements against your device’s operating system version BEFORE you try to install apps. You may need to buy a new phone if your current one’s operating system can’t be upgraded.

Bottom line 2: The government and other organisations are locking out and marginalising many people by requiring them to use technology they may not be familiar with, may not own (or be able to afford to own), and may not already use or don’t want to use.

*******

Background

Brief summary: The Western Australian (WA) government will require proof of vaccination status for many establishments after 31 January 2022, including restaurants and cafes. They’ve spend a bucketload of $$$ on developing the ServiceWA app that will store such information and ultimately replace the SafeWA contact tracing check-in app and the G2G pass for travellers into the state once the borders open on 5 February 2022.

Because the ServiceWA app is a state thing and it has to link to some federal information (e.g. vaccination certificates are held by Medicare [federal]), the app was designed to link to your MyGovID and Medicare apps, both of which you need to install on your device before installing and connecting the SafeWA app. The steps are many and convoluted and I’m sure will put many people off using the ServiceWA app as a result.

Issues

On my Facebook page, I raised several issues with these apps in general. Even though I was able to successfully link everything together for myself, this will NOT be the case for many. Here’s a quick summary of the issues:

  • If you have an Android device (that’s all we have so I can’t speak for any ‘i’), you first need to have a Google account to access the apps in the Google Play Store.
  • If you don’t already have MyGovID and Medicare set up, you have 20+ steps to do. They warn you this will take at least 30 minutes. Many will bail before completing the sign up process. Way too confusing!!!! (see the Further Information section for links to the steps)
  • If you haven’t set up MyGovID before, you will need at least two pieces of ID (e.g. passport, drivers licence) that you can either enter manually in the apps or scan and upload.
  • Oh, and you also need a smartphone with a recent operating system!!! And a data plan (at least WiFi). Some people won’t have a smartphone, others will have a phone but it’s too old, some don’t have/use the internet in any way for whatever reason (age, impaired ability etc.), others may have a phone for just a phone and not have a data plan or want one. The MyGovID app requires Android 7.0 or higher and phones just a few years old do not have that (ask me how I know…). Which means buying a new phone!
  • Setting up the apps requires the user to have their OWN email address and OWN device (yes, I confirmed this with ServiceWA). So pensioners, for example, who have a shared phone and shared email address will either have to use paper documentation to enter a café or buy another phone and get another email address and then get someone to help them set all this up. I feel for the hospitality staff who will be inundated with very confused and angry patrons. So many questions… so few answers.
  • You will still be able to check-in using a paper copy of your vaccination certificate. However, getting a copy isn’t simple if you don’t have a computer or a MyGov account. Paper documentation will still be accepted, but again, the boffins in these government IT departments seem to think everyone has easy access to a computer and printer and knows how to use one, AND has a MyGov account so they can access their Medicare records to get the PDF of their vaccination certificate. If you don’t then your vaccination provider, such as a GP or pharmacist (NOT a vax clinic), can print your immunisation history statement for you. Or you can call the Australian Immunisation Register (1800 653 809) and ask for your statement or certificate to be posted to you—this can take up to 14 days to arrive in the post.
  • There’s a massive assumption that people have the technology and ability and willingness to use apps. The exclusion of those who are elderly or incapacitated in some way (and there are MANY ways you can be incapacitated) or who cannot afford a mobile phone and the assumption that everyone has an individual phone AND that phone has a data plan (and therefore apps) AND has an individual email address AND can use all this stuff is a false one. So, my 90+ year old parents will be carrying their printed vax certificates with them to their local coffee shop come 5 Feb.

Further information

[Links last checked January 2022]

 

h1

LG CI OLED TV: Changing how the subtitles display

November 12, 2021

This information is for me in case I ever need to do this again.

**********

This week we replaced out 12-year-old not-very-smart-TV (55″ Samsung) with a you-beaut 77″ LG CI OLED. It has a LOT of settings, but one that’s pretty hidden and hardly touched on in the online help is subtitles—all I could find was how to turn them on or off (under the Accessibility settings). I went down a rabbit hole of modifying SRT (subtitle) files for those programs that had them, but with no joy. The subtitles displayed in a large white font in the lower half of the screen. A bit of Googling suggested that changing the SRT format to ASS might help as there was more you could do with the ASS subtitle file, like changing its position on the screen, putting an opaque box behind the subtitles etc. It was easy enough to change the file format using the free Subtitle Edit program, and easy enough to interpret and modify the code (especially with the help of this website: https://fileformats.fandom.com/wiki/SubStation_Alpha). However, almost all the forums etc. suggested that while this might work for subtitles displayed on your computer (e.g. playing through VLC player), most TVs had their own settings and these overrode anything you might set in the subtitle files. Great. I hadn’t found any settings that might change the subtitle display, only the one for turning them on an off.

So I did some testing…

  • I played a program without its accompanying SRT file to see if the subtitles were embedded in the program—they weren’t. With no subtitle file, there were no subtitles.
  • With the SRT file, the subtitles displayed, but none of the changes I’d made to the font colour were shown.
  • I removed the SRT file and replaced it with an ASS file that I’d modified in Subtitle Edit to change the colour of the text, add an opaque block behind the text, and shift the subtitles to the top of the screen. The subtitles displayed fine, but not with ANY of the settings I’d changed—they were still in largish white text and partway up from the bottom of the screen.

Finally, I decided to see if there was anything at all in the on-screen playback controls for the program. With this TV, you have to press any button or shake the remote to get the basic playback controls (rewind, pause, fast forward, plus a timeline). Underneath were instructions to scroll down to find more controls. I hadn’t done that, so gave it a try. And there on the far left of the extra controls was an icon for subtitles!

And when I clicked it, I got all sorts of things I could set! I could change the text colour to one of about 6 different colours (I chose yellow—white is hopeless on a white background), I could set the font size to something smaller (I think I went with the smallest—it’s still easy enough to read on this large screen), and I could set the position of the subtitles, to a degree. The default position is 0, and the options range from -3 to 3. I tried 3 and the subtitles moved up quite a way on the screen (but still in the lower half—you can’t get them to display at the top at all), and then I tried -3 and the subtitles moved down almost to the bottom of the screen. Not perfect, but MUCH better than the defaults.

I think TV companies are doing their customers a disservice in having such limited options for subtitles. It’s all very fine having wonderful picture and sound, but many people rely on subtitles—at least part of the time—when they watch TV (hard of hearing, wanting to watch in silence when the rest of the house is asleep, strong regional dialects and accents, mumbled speech, etc.). Subtitling technology seems to have hardly changed, and I think it’s ripe for attention, as this ex-Samsung designer states: https://superavi.com/subtitles-were-never-designed-the-missing-element-in-tv-typography-design/

(One thing I haven’t figured out is why the subtitles sometimes jigger and shake—my husband thinks there’s a correlation between laughter and this jiggling, and he might be right. More observations are required… there’s certainly nothing in the SRT files I checked that would do this.)

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.