Archive for the ‘Technical writing’ Category

h1

How long before this danger causes a problem?

May 31, 2017

In the ‘what were they thinking’ category comes this — replacing those moisture-absorbing gel packets in products with something that has a similar size, shape, and feel to the product!

I purchased a container of glucosamine tablets recently, and when I opened it, I found a blue plastic cap-like thing instead of the gel packet. Tell me it doesn’t look like one of those bullet-like tablets! How could a person with limited dexterity, compromised touch, or vision problems distinguish this blue thing from a tablet? Seniors tend to be those who take glucosamine, and they are more likely to have dexterity, touch, and vision issues as they age, so I’m just waiting for the news headline that says someone was hurt or injured or even died from ingesting one of these blue plastic cap things.

What were they thinking??? Did no-one see that you need to clearly distinguish the product from something that isn’t the product and shouldn’t be ingested? At least the gel packets were a different shape, different feel, and made from quite different materials, enabling them to be ‘not like the others’.

h1

ACES Conference: 2017

April 13, 2017

I attended (and spoke at) the American Copy Editors Society (ACES) annual conference in St Petersburg, Florida in March. I loved the Tampa/St Pete area!

Just for my records, here are the sessions I attended, with a brief summary for each of them.

Thursday March 23

  • Quick fixes you may have forgotten about (Merrill Perlman): A nice refresher of things that you can overlook when editing. Merrill is a funny, engaging speaker.
  • Catch as catch can (John Russial): Math!! Especially the difference between percentage and percentage point increases/decreases. Valuable.
  • Professional Etiquette: Navigate networking without making enemies (Christina Frey, Sarah Grey, Barbie Halaby, Heather Saunders): Very professionally presented, with seamless segues between members of the panel. Lots of content and great ideas.
  • ‘Word by Word: The secret life of dictionaries’ (Kory Stamper): Kory’s book had just been published a few days before the conference and this was her first-ever reading from it. She read an excerpt from the first chapter. It was so good, I ordered a copy online immediately afterwards (it was a hardback and only 24 copies were available at the conference) — my ordered copy beat me home. I’m about halfway through it and thoroughly savouring every word. Highly recommended for word nerds!

Friday, March 24

  • The Online Misinformation Ecosystem (general session) (Craig Silverman): Craig works for Buzzfeed. This session was great on pointing out how news and social media can manipulate a story.
  • Computer-Assisted Copy Editing: Using Tansa’s Products for Clear, Concise and Consistent Content (Chris Grimm): Excellent overview of some online tools available for checking consistency. However, each requires a link back to an online server, and so wouldn’t be acceptable to my main client.
  • The Editor as Writer: Essential Tools and Strategies (With Music!) (Roy Peter Clark): Great session, covering many basic (but often forgotten) strategies.
  • Faking Extroversion as an Introvert (Samantha Enslen, Rachel Godward, Laura Lattimer): Good session, but unfortunately Sam only ended up with about 3 minutes to cover all she had to say, which was a shame as she’s an excellent speaker.
  • ‘French toast’ vs. ‘french fries’: The Wild West of Food Editing (Wendy Allen, Janet Keeler): I loved this session! I don’t do food editing, but I cook, eat, and dine out, and read cookbooks and menus. I’m sure that qualifies, right? Oh, I was the only one in the room who knew the difference between grazer (an animal that grazes on grass) and grazier (a person who looks after such animals) — obviously ‘grazier’, which is well known in Australia, is little known in the US.
  • Banquet – keynote speaker Anne Curzan: Introduced us to ‘grammando!’, and recommended we use it instead of ‘grammar nazi’

Saturday, March 25

  • The Art of the Possible: The Dictionary as Authority of a Changing Language (Kory Stamper, Peter Sokolovksi, Anne Curzan): Lexicographers and linguists — these are my people and they are ‘on fleek’! :-)
  • Save Time and Your Sanity: Increase your Efficiency with Microsoft Word (me!): The room held about 70 seats — all were full, and about another 30 people were on the floor or leaning on the walls, which is tough for 90 minutes! Thanks for coming — and for staying, if you were one of the floor people.
  • Government Contract Editing–Guidelines to Make It Work (Elizabeth LaPlante, Helen O’Guinn): Good advice on plain language when writing and responding to RFPs etc.
  • How to Diagram Sentences — and Why (Lisa McLendon): A whirlwind trip through sentence diagramming, with examples for us to try. This wasn’t taught in Australian schools when I was growing up, so was unfamiliar to me, but I like the structure of it.
  • Lightning Presentations and Closing General Session: More whirlwind presentations. Kudos to the presenters!!
h1

The problem with ‘simple’ instructions

December 18, 2016

Bottom line: Simple instructions are good, but don’t make them TOO simple. Include key prerequisites. Users familiar with the product may choose to ignore the instructions, but new users will thank you for them.

The problem with ‘simple’ instructions is they often leave out critical information, assuming that the user already knows it. But what if this is the first time you’ve used a product? Or if you just don’t know (or forget) how it connects to other stuff?

What prompted this post? I have an under-sink water filtration system — the previous one required a plumber to fit the replacement cartridges, but this new system (Puretec’s Puremix X6 System) allows the user to change the cartridge ‘like changing a light globe’. The system has been in place for 12 months now, so it was time for me to replace the cartridge.

The only instructions on the new cartridge’s box were ‘Quick-change cartridge, easy to replace — just like changing a light globe.’ That’s it. I thought there might be instructions on a leaflet inside the box, but no. Nothing. There was an instruction on the new cartridge itself — ‘Twist old cartridge from head [what’s the ‘head’??] and twist new cartridge into head until firmly sealed. After installing cartridge flush unit for 5-10 minutes.’ But that was it.

How hard can it be?, I thought.

Well, at least for the first time, much harder than the instructions lead you to believe!

I pulled the new cartridge out of the box and found it had a blue cap covering the top — do you remove this or not? For those big water bottles you get delivered, you DON’T remove the blue cap, but that was the only reference point I had. And remember, there were no clear instructions to tell me what to do.

So into the cupboard under the kitchen sink I went, removing all the paraphernalia in front of the existing cartridge. I untwisted the existing cartridge to remove it — and water gushed EVERYWHERE!!! Why? Because they didn’t tell me a key step before changing the cartridge and that’s to turn off the mains water to that unit!!! Yes, I should have realised this, but I’ve been sick the past few days, so my head’s not in a good place. But if I was a young 18-year-old in a rental apartment and had to change the cartridge, would I know to turn off the tap first, or even how to find/identify that tap?

After a few seconds of water gushing everywhere, I turned off the mains tap. Then I spent the next 10 minutes mopping up — fortunately, we had an old bath mat under the water cartridge in case of any minor leaks, and it absorbed most (but definitely not all) of the water.

OK, now everything’s mopped up and the water’s off, so I untwist the existing cartridge and remove it. That was pretty easy. I saw that the old one didn’t have a blue cap on it, so I figured I needed to remove the blue cap on the new one. This required powers of extrapolation, which my brain wasn’t dealing well with at all. Off came the cap.

Next, to seat the new cartridge in place of the old. Not so easy. Why? Because there are notches in the top of the cartridge and you have to line them up precisely with the static part of the system (that’d be the ‘head’, I figured). Fortunately, we didn’t have quite enough room under our sink for the plumber who originally installed the system to screw the ‘head’ to the back of the cupboard (as per their images on Puretec’s website), which meant I was able to turn it at an angle where I could see the notches that had to line up. After a few attempts, I got this right and was able to seat the new cartridge and twist it to tighten and seal it. I then turned the mains water tap for the filtration unit back on, then the tap for the water filter spout (which gave me fright by spitting air at me for a few seconds before the water came through), and then ran the tap for about 7 minutes, checking inside the cupboard to make sure there were no leaks.

It shouldn’t be this hard! The box the cartridge comes in, and the cartridge itself, are large and there’s plenty of ‘white space’ on them. To add a few steps would have prevented the issues I (and no doubt others) encountered.

Here are my steps for replacing a Puremix X6-R water cartridge:

  1. Turn off the mains water tap to the water filtration system; this is likely inside the cupboard below the system.
  2. Take the new cartridge out of the box and pull off the blue cap. Note the single and double notches on the ‘shoulder’ of the cartridge.
  3. Twist the old cartridge in an anti-clockwise direction (left) to remove it from the head unit.
  4. Position the new cartridge so that the notches line up with the corresponding parts of the head unit.
  5. When aligned, push the cartridge up into the head unit.
  6. Twist clockwise (right) to tighten fully.
  7. Turn on the mains tap.
  8. Turn on the tap of the water filter spout — wait a few seconds for the air to clear the line and water to start running, then leave the water running for 5 to 10 minutes to flush the new cartridge.

As a final step (not listed above), I’d also add some information on how to dispose of the cartridge appropriately — including whether the water inside it has to be drained or is sealed in there.

 

h1

Noises in manuals

September 7, 2016

I purchased a new freezer this week. One of the first things I do when I get a new appliance is read the instruction manual. Yes, I know that only about 10% of the population reads an instruction manual, but I consider it a way to learn about the product AND a professional courtesy I extend to all those fellow technical writers who write them.

What made this manual different? It has a ‘noises’ table! After reading it, I think ALL appliance manuals should have one of these, if the appliance makes various noises during its operation. I know that products like UPSs have info on the various beeps and alarms, but this table listed the normal operating noises the freezer makes. So simple, and just brilliant.

noises

h1

EditorsWA Winter Seminar: Sex, lies and editing

August 31, 2016

On 13 August 2016, I attended and spoke at the annual Winter Seminar, held by EditorsWA, the Western Australian branch of IPEd, the national professional association for editors.

Here are my notes from the three sessions; the second session (on plain language) was mine, so there are no notes for it.

Session 1: Sex, lies, and blogging (Amanda Kendle)

  • Tweets – 140 chars forces you to be concise, remove redundancies, ignore punctuation, and abbreviate
  • Blog/social media writing is quite different
  • Style tends to be casual
  • Repetetive words/phrases may be there for SEO purposes, so not just redundancies
  • Each type of social media requires different styles of writing (Facebook vs Twitter vs LinkedIn)
  • Tips for developing a good blogging voice:
    • write like you talk
    • consciously choose your level of informality/casualness
    • use contractions and first person
    • read other blogs and identify styles you enjoy
    • tell a story, no matter what the topic is.
  • How to edit content for blogs and social media:
    • read aloud to get a good feel for appropriate ‘friendliness’
    • communicate clearly with clients about the style they want to use
    • give clients examples of blogging and social media posts that are of a suitably informal standard
    • suggest clients do voice recordings to transcribe from if they are writing in an overly academic or formal way.
  • NOTE: the rules are ever-changing and highly flexible.

Session 3: To ‘do it’ or not to ‘do it’: Things to consider before including a sex scene (Chloe Stam)

  • Various types of sex scenes
  • Should there be a sex scene?
    • in some genres, it’s expected.
    • some publishers have quotas!!! (e.g. three sex scenes, this many pages apart…)
    • realism – sex is part of human life, and in current culture
    • relevance to plot — if no function, don’t do it.
    • sex scenes in YA novels — if true to the characters, don’t avoid, but tone it down, especially as written from first person; sex is a reality with YAs, but don’t centre entirely on sex; don’t introduce unrealistic/harmful ideas (e.g. BDSM, ‘porny’ sex)
  • Even if graphic and anatomical, sex is ultimately about emotion and communication; emotion doesn’t mean love.
  • Editing sex scenes:
    • male or female point of view?
    • senses — use sensual impression to pull readers in to the story
    • conflict of the characters — what’s at stake? is something holding them back?
    • pacing — build-up to the sex scene with increasing sexual tension
  • Character development:
    • how does the act change your characters, show who they really are, or what they’re afraid of?
    • who initiated the intimacy, how is it displayed, what happens when it’s over, are their reactions equal?
  • There’s a ‘Bad sex in fiction award’!
  • Representation of sex and people:
    • diversity — normal in life, therefore should be normal in books; POC, queer, other minorities struggle to find positive representation in mainstream media; not about meeting a quota or making a statement; makes the book more interesting
    • default — characters are seen as white unless otherwise stated
    • asexuality — don’t find other people sexually attractive; often depicted as non-existent, needing a cure, robotic characters
    • people with disabilities — how are they portrayed? are they shown as sexual, or just dealing with their disability? Are they 3D characters and a real part of the story?
    • exoticism– calling someone ‘exotic’ reminds them they are different and emphasises their ethnicity; lots of stereotypes!! (mostly around women, esp. black, Asian)
    • queer – LGBTI etc. Often written about negatively; rarely a 3D character where their life doesn’t revolve around sexuality
    • elderly — seen as sexless and infantilised; disparity between men and women
    • self-love — seen as natural for men, but deviant for women
    • BDSM – requires trust, communication and emotional maturity. It is not sex and violence with emotional manipulation.
  • Sexual violence — avoid:
    • rape to punish female characters
    • rape as a backstory to make a ‘strong female character’
    • rape/murder only to affect male protagonist (women in refrigerators)
    • rape for shock factor/titillation
  • Disproportionate levels of rape against women as opposed to men – therefore masks issues of sexual assault against men
  • Journalistic reporting on sexual violence, victim blaming etc.

Session 4: The plagiarism games (Ffion Murphy)

  • What constitutes originality and does it matter any more? Literary theft, mimicry, borrowing, homage, or inspiration?
  • Universities invest huge amounts of $$$ in detecting plagiarism (e.g. Turn it in)
  • What is ‘originality’? where is the line? Is this idea of a line or border misleading even corrosive or stultifying?
  • Transformation — can be derived from another but must be significantly different and must transform the ‘original’, re-patterning of earlier works.
  • Inspiration vs copying:
    • work needs to share at least some qualities of what has been judged ‘good’ in the past
    • value is located in an act of digression, transgression, homage to, or transformation of what has come before
    • must be an acceptable type of copy

 

h1

World domination achieved!

June 11, 2016

Yesterday I got an email from a US friend. He’s in Budapest (Hungary) attending a tech writing/user assistance conference (UA Europe). He’s in a session presented by someone from The Netherlands when he spots a screenshot of a page from this blog! He has enough time to capture it on his phone and send it to me. How cool is that — a Dutch presenter showing a page from an Australian’s blog, seen and captured by an American, in Hungary!

Even cooler, the presenter said that it was great example of a ‘perfectly complete task explanation’ and ‘This rocks!’ My work here is done — I think with this, I have achieved world domination ;-)

20160610_100935

(In case you’re interested, the blog post the speaker referenced was: https://cybertext.wordpress.com/2011/08/08/word-insert-a-multi-page-pdf/)

h1

PowerPoint: How to show another app

January 5, 2016

This post is for me so I don’t forget what to do!

In days gone by, if you did a presentation using Microsoft PowerPoint (for Windows) and you linked to another app for demo purposes (e.g. Microsoft Word), then clicking the link would open the app on the screen, covering the presentation until you pressed Alt+Tab to return to the slide show.

However, in more recent versions of PowerPoint (2010 at least and later), this function seems to be gone when you connect your laptop to an external monitor, such as a projection unit. Instead, you get ‘presentation mode’ on your laptop and the presentation on the big screen, but when you click a link to display another app, nothing happens on the big screen, even though you get the linked app showing on your laptop.

This is disconcerting as you think the audience can see what you see, and frustrating as you try to figure out how to get back from the presentation to show the app on the big screen, then back to the presentation again. I’ve been caught with it in the past three presentations I’ve done, and it totally throws you off your spiel, and takes up precious time as you (or a techie) try to get you where you need to go.

Because I’m doing at least a couple more presentations this year, I decided to figure out the best combination of settings to use to display everything I need on the big screen. I connected my laptop to an external monitor and played with the settings to get a combination that works for me.

Here are my settings for future reference (do these in order):

  1. Windows 8.1: Control Panel > Display > Project to a Second Screen > Duplicate
  2. PowerPoint 2013: Slide Show > Monitor — set to Primary
  3. PowerPoint 2013: Slide Show — turn OFF Use presentation mode

What this does is duplicate exactly what’s on your laptop on the big screen. The upside is that you can now click a link in your PowerPoint and open another app and the audience will see it. The downside is that everything on your desktop, task bar etc. can be seen by the audience, so the usual caveats for presenting from many years ago still apply (i.e. don’t have anything on the screen that’s private!).

[If you have an easier way to do this, please share in the Comments]