Archive for the ‘Technical writing’ Category

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]

h1

The usability of gravestones and memorial markers

October 5, 2015

Not something perhaps you’d think about… But none of us is getting out of here alive!

A bit of back story… In some of my spare time, I transcribe information for various genealogical projects and digitized newspapers. I do this from my computer, so it’s easy to volunteer a few minutes here and there, and thus help add to the wealth of information available to the world.

Recently, I found a website — BillionGraves — that has the lofty aim of photographing, mapping, and transcribing the headstones and memorials from graves throughout the world. Although some cemeteries have their records online and are searchable, many don’t, particularly those cemeteries that are no longer used and are rotting away. BillionGraves uses the power of crowdsourcing to gather and process this information. In addition to their website where you can transcribe information on headstones, BillionGraves also has an app you can download to your phone or tablet so that when you’re out and about you can visit an uncatalogued cemetery, take photos of the headstones, and upload them to the site (the geographic coordinates upload with the photos). Then you can either transcribe them yourself via the app or website, or leave them for others to do.

What a cool idea for going for a weekend drive and picnic, and having a purpose for that drive! (yes, I’m weird like that…) BillionGraves has the locations of long-lost cemeteries on its website, so you can plan to visit one that hasn’t been catalogued and that you may not even know exists because it hasn’t been used in decades. For example, in Western Australia where I live, we have many bush areas that are peppered with graves from the early settlers. The houses and settlements have long gone, but some of the graves remain.

So what has all this got to do with usability?

Remember I said that none of us is getting out of here alive? Well, most of us (at least, most of us in the ‘developed world’), will be either buried or cremated and will have either a headstone or memorial plaque made in our honor and placed in a cemetery somewhere. A little bit of forethought as to how that memorial is designed and what goes on it could make it VERY usable for future generations researching your family tree.

What’s become evident to me while transcribing other people’s information is that so much of that information is not complete, is insular (making assumptions that readers of the memorial will be reading it in the same country and century it was made, for example), and/or is unreadable.

Recommendations

Here are some things I recommend (in no particular order) based on what I’ve discovered while transcribing headstones etc. and based on what genealogical researchers need to know. If you have any say in what goes on a loved one’s memorial (or your own), then consider these recommendations — future generations hunting you down will love you for it!

  • Good contrast is essential. Pink granite is an awful carrier for carvings and most colors used for text — much text is unreadable, and the color and mottled nature of the granite makes it hard to photograph. Gray granite with just carved letters and no color is nearly as bad, as are gold letters on mottled gray granite (see the unreadable images below).
  • List a date of birth AND death — you don’t need ‘died aged xx years’. A date of death is usually given on a memorial, and sometimes an age at death, but rarely is a date of birth given. Genealogists put a lot of store in dates of birth AND death, and an age is just not good enough. If you state that the person died on 15 June 1985 aged 76 years, were they born in 1909 or 1908? Depending on the birth month it could be either. A date of birth is likely fewer characters to pay for than a ‘died aged xx years’ statement, AND confirms to future generations that they have the right person AND provides a date of birth if it is missing from other records.
  • List the maiden (or birth) name of a married female. Maiden names (awful term…) of females are rarely given, yet they are crucial to genealogical research. So many women in family trees get ‘lost’ when they marry as their married surname is not known. And if they marry more than once, they are even harder to find. Including the maiden name helps identify if that person is part of your family tree.
  • Use four-digit years. Two-digit years are useless. Does 15 June 85 mean 1885 or 1985? Or some other year? Memorials can last for several centuries, so make sure there is no confusion as to which one. Don’t assume that a future reader will be from the same century.
  • Write months in letters, even if abbreviated. Numeric dates only are problematic for researchers and transcribers from other countries. Does 4-5-1962 mean 4 May 1962 or April 5 1962? Depending on where you went to school, it could be either! Better to use 4 May 1962 or 5 Apr 1962 to remove any possible confusion. Using a three-letter abbreviated month is fine.
  • Use the full name of the deceased, including any middle names. Middle names are important in helping distinguish many individuals in a family tree with the same name.

 

Examples

graves01

Mottled gray granite with gold carved text — impossible to read from a photograph.

graves06

Pink stone of some sort (likely a sandstone not granite, but I’ve seen plenty of pink granite ones as bad), with carving but no colour used in the carved text (or it has worn off). Impossible to read from a photograph.

graves02

Good contrast, full name of deceased, has first name of wife (a bonus), dates of birth AND death, but uses numerals for the months (not too much of an issue in this case as they can be figured out by someone with a North American background and can’t be confused), and only two-digit years.

graves03

Great contrast, has dates of birth and death (with abbreviated months in letters and full years), has names of parents and siblings, has middle name.

graves04

Great contrast, has dates of birth and death (but only numerals for months so potentially confusing for a transcriber from a different country), full years, full names of both people (but no maiden name for the female), and then there’s some information that has no meaning or connection to anyone outside the family (i.e. who is ‘Pat’? a son, daughter, relation, friend??)

graves05

Even though I can’t read the language of this one (Russian?) and couldn’t transcribe it, it has great contrast, lists dates of birth and death (but months are in numerals), and uses full 4-digit years.

h1

Epic fail, Samsung

May 29, 2015

An epic failure of design and of support, and a waste of 2 hours of my time. And I still don’t have a solution.

samsung01

samsung02

samsung03

I was trying to change the battery in the Samsung mini remote control for my TV. I couldn’t remove the battery cover. So after checking the manual, getting my husband to try, and then checking online for solutions, I start an online ‘live chat’ with Samsung Support. After some mild pleasantries and discussion of what I’ve already done, we get to this (my asides in italics):

Support: Can you see a small space which can enter your nails to remove it?

Me: NO. Only the thin line between the compartment and unit. There’s nowhere to put a fingernail or screwdriver. No lip, No latch. Nothing. It should be easier than this!

Support: I do apologise for the inconvenience.

Me: Is there a YouTube video that shows how to remove it?

Support: I do apologise as we are unable to access third party website. Have you tried searching it?

Me: yes, for about an hour before I started the chat. What use is a remote control that doesn’t have an easy way to change the battery?

Support: I understand. If that would be the case, we recommend to have it checked by our technician.

Me: That’s ridiculous! Can I get a replacement mini remote?

Support: I sincerely apologise for the inconvenience this has caused you.

Me: Not your fault, but a SERIOUS design issue if the battery can’t be changed!

Support: If you wish to purchase a mini remote control, you need to get in touch with our major service centre for spare parts.

Me: So, there’s no way you can tell me how to change the battery? Why is it so tough to turn? Is it glued in? Can we prise the unit apart?

Support: Have you tried press the battery? Let see if it will bounce back.

Me: No, that didn’t work. (It’s the compartment I’m trying to open to get to the battery, so obviously it’s impossible to press the battery if I can’t open the compartment!)

Support: Have you also tried using your nails to turn counterclockwise?

Me: It’s already turned counterclockwise. Trying to use fingernails would wreck your nails. There’s a slot for a coin. I used a coin. As I told you at the beginning. It WON’T turn freely and once turned it WON’T pop out.

Support: What about clockwise? (BTW, the manual says counterclockwise!!)

Me: No. It wouldn’t go clockwise when I first tried, and now that it’s counterclockwise and with all the attempts I’ve made with a coin, it won’t turn clockwise now either as the slot is burred by forcing the coin. I give up.

Support: As we have exhausted the needed steps, it will best to have it checked by our technician. I understand just how frustrating this issue has become for you, and I apologise for the inconvenience.

(UNBELIEVABLE!!! Exhausted all the steps??? What steps? I’d already DONE the steps before I contacted them!! He offered nothing more and had no clue. His only solution was to send it to their techie. For an issue related to opening a battery compartment!!! What good would that do? We still wouldn’t know how to open it successfully.)

Me: what does that involve? Will you pay postage both ways?

Support: You need to bring the remote control on the service centre and our technician will check it. I’m unable to quote any amount. The cost of the repair will be provided after the assessment.

Me: Forget it. It’s not a repair! It’s a design fault!!! And I live outside of a country town. Do you have a service centre in XXXX, Western Australia?

Support: I understand. I am very sorry for the trouble.

(He then gives me an address in Canning Vale, Perth [Unit 3, 7 Mordaunt Circuit, Canning Vale, 6155; ph 08 6258 0000]… a 4-hour round trip for me. For a battery compartment that won’t open… I’ll take it into Harvey Norman’s next time I’m in XXXX to see if they can figure it out… This has taken nearly 2 hours so far and I still can’t open the battery compartment! Sheesh!)

Update 31 May 2015: So, the guy at Harvey Norman’s wasn’t able to open the battery compartment either!! However, he did give me some vital info and that was to match up the two tiny dots (one on the compartment cover and the other on the unit). That info was NOT in the manual. With a large screwdriver he was able to turn the compartment cover a bit more, but not enough to line up the dots. Again, the only other option was to force it open, thus running the risk of breaking it. He spent 20 minutes on it… With the cost of my time, his time, the Samsung Support person’s time, this has cost a LOT for no result. In hindsight it would’ve been cheaper ($35) to buy an after-market remote in the hope that it worked… My husband suggests sending the remote to the Samsung tech people in Perth, with a note explaining everything done so far – he reckons they might replace it. I may just do that.

Update 3 June 2015: I called Samsung Support in Australia. The guy couldn’t help me (and also said it shouldn’t be this hard) and referred me to the Canning Vale service centre. The lady there couldn’t help either and said they couldn’t repair it and I’d have to consider purchasing a new one from the spare parts division. She put me through to them. I could get a replacement remote for $30 direct from Samsung (I’d seen them online for $35 so thought that was a good deal), but when I enquired about postage I was told it had to come from Sydney, would take 7+ days (that would be 10+ days to get to me), and postage was $20!!!! For a tiny $30 item. Yeah, right. So I went online and ordered it for $34.95 plus overnight flat rate postage of $9.90 to anywhere in Australia. One of the first things I’ll do when I get the new unit is attempt to open the battery compartment to make sure I can do so without issue.

Sheesh!