Archive for the ‘Technical writing’ Category

h1

New tribes

July 31, 2017

Foreword written for Southern Communicator, Issue 41, June 2017

**********

New tribes

Tribe: Colloquial (humorous) a family or class of people (Macquarie Dictionary)

In September 2008, after 16 years in the software technical writing world, I segued into editing technical documents. It was just as the global financial crisis was happening, and a time when mining and software companies (my main source of income) were getting rid of contractors to preserve their bottom lines. I lived in a rural area three hours’ drive from Perth (Western Australia), so was fortunate to land a temporary three‐month telecommuting contract with a global oil and gas company—I’m now in my tenth year with them—editing some of their Word documents. Yes, Microsoft Word.

Word is still heavily used by corporates for much of their day‐to‐day documentation and reporting. We can talk all we like about how other software is better for constructing documents, managing the review cycle, formatting, publishing to various outputs, and the like, but the reality is that other software (for example, Framemaker, InDesign, Author‐it, and so on) often remains the domain of specialist tech and marketing communications people, with little inroads into mainstream corporate life.

As I moved into this different, but related, editing world, I was still very much attached to my technical communication ‘tribe’ (I attended and spoke at techcomm conferences until 2014). But eventually I decided it was time to embrace this world I’d inhabited for six years. And what better way to embrace a new tribe than by hanging out with them in the places they frequent. For me, that’s conferences and online.

Dr Google told me about various professional and informal editing organisations, some of which were very specialised (for example, medical editors, thesis editors). I was already a member of the Western Australian editing society, which recently became part of IPEd, the professional group for Australian editors. IPEd holds a two‐day conference every two years, and the state branch holds a one‐day seminar each winter. But, like Oliver Twist, I wanted more.

Professional editing groups in North America and Great Britain were my focus, especially those that held multi‐day annual conferences. But which to choose? Eventually I opted to join the American Copy Editors Society (ACES); ACES’ original focus was newspaper copy editors, but now covers all types of editors. I attended and spoke at my first ACES conference in the US in 2015—I was a total newbie, only knowing one other person attending that conference. This was so different to the techcomm conferences where I knew many people. I’ve since attended and spoken at the 2016 and 2017 ACES conferences, and the circle of those I know in this new tribe is growing wider.

Speaking at a conference is a great way to meet people—it’s amazing how many stop you in the hallway to tell you how much they enjoyed your session, ask you a question, or just strike up a conversation over a drink or a meal because they feel they know you because they’ve heard you speak, or, as an Australian in the US, because they ‘just love your accent’! Speaking is also a terrific icebreaker, and I can’t recommend it enough for those who find themselves very lonely at a conference. Put yourself out there and offer to speak. The ASTC conference is usually held each October, so consider putting in a submission to speak at the next one, or try the TechCommNZ conference, held every two years.

Another tribal behaviour is the chat around the camp fire, or today, around the coffee machine. But how can you informally pick fellow editors’ brains when you work alone and are physically distant from your work colleagues, or don’t have any work colleagues? Join an online group. Despite the time zones, I try to participate in the monthly, hour‐long #ACESChat on Twitter. I also hang out at the Editors Association of Earth (Facebook group), where editors from around the world help each other decipher awkward sentences, solve Word problems, share bloopers, talk about language variations and regionalisms, and so on. And because we’re global, there’s always someone awake somewhere to help with a curly question, or offer moral support.

Tribes—it’s all about finding ‘your people’ and the feeling of belonging when you do. So search, join, attend, participate, speak—hang out with your people because it’s good for you professionally and it’s good for your soul to be with like‐minded people, even if just for a short while.

References:

[Links last checked July 2017]

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