Archive for August, 2013

h1

Flying edits

August 26, 2013

Something came to me in a conversation I was having the other day about some of the documents I edit — these documents are like plane trips! Bear with me here… I haven’t gone crazy ;-)

Qantas A380 at LAX

Qantas A380 at LAX with American Airlines Boeing 757 for size comparison; note also the size the bus (Image from: http://www.generalgeneral.com/at-the-lax-airport/)

A bit of background… I edit hundreds of documents a year for two teams on a big oil and gas project. While many documents come from the same group of authors (usually reports and plans from environmental scientists), I also get documents that have come via third parties (e.g environmental consultants) or from other members of the team who don’t write reports very often. As a result, I get all sorts of documents to edit, from 12-page quickies to 500-page behemoths.

I’ve also flown on many long plane trips and have seen my fair share of the inside of planes (it takes at least 3 hours flying time to get from my state’s capital to our closest state’s capital, and about 20 hours flying time for me to get to the US west coast from the west coast of Australia).

So how is editing a document like a plane trip?

The basics

All documents I edit have the same basics no matter what size they are — they’re based on a corporate template (or should be!) and have the same front matter (title page, document control information, table of contents, headers/footers, usually a terms list and often a references list).

All planes have the same basics no matter whether they are an A380 or a small Bombardier or Embraer commuter plane (‘puddle jumper’) — wings, fuselage, cockpit, engine(s), steering mechanism, etc.

So no matter what document comes to me, I have to deal with those basics every time. Just like a pilot has to deal with the aircraft basics, no matter what the aircraft’s size is.

Pilot quality

This is analogous to author quality. Some authors (pilots) are just more experienced with certain types of documents (planes) than others. And it shows in the smooth writing (smooth flight). Some authors have a good understanding of Microsoft Word (our authoring environment) and can make it do what they want it to do; others have to rely on me (their co-pilot) to help them get control of their document when Word goes awry for them.

Journey length

By the time some flights take off, they are ready to land again — these are the puddle jumpers. I liken these to the 12-page Word documents I get, which I can usually edit in a short time period. Conversely, the long-haul Qantas flight between Sydney and Dallas (the longest non-stop flight in the world?) is like editing a 500-page Word document. It takes an awfully long time to get there, you might fall asleep along the way, you need sustenance to get you through it, you need to get up and walk around every hour or so, and you may need to change activities every so often to keep your brain fresh. And when you get off that flight (finish that document), you are ragged around the edges — your mind is numb, and you’re not thinking clearly.

Cabin quality

Some documents are just first class. The author knows what they are doing, they know how to write, and the quality just shines through. These documents are a pleasure to edit. Business class is nearly as good, followed by premium economy. And then there are the economy (cattle-class) documents… The ones that take forever to edit, even if they are only short. The ones that are crammed full of unnecessary words and sentences that aren’t coherent, and that have a lot of overhead baggage.

Winds

Documents that are hard to comprehend are like really strong headwinds — you spend an awful lot of time not making much progress and you are buffeted around by the process. Conversely, a well-written document (no matter what its size) is like surfing the jet stream — you can fly through that baby and complete it in a time that’s often quicker than it takes to edit a much shorter document that’s hard to comprehend. For example, it has taken me two days to edit some 40-page documents, whereas I can normally edit a well-written 150+ page document in two days.

Holding patterns

The documents I edit go through several rounds of internal and external reviews before they are released. I think of these as long-term holding patterns, as it may be several months between when I first edit the draft document and when I edit it for the final time prior to release (landing). Some documents go through more of these review cycles than others, just like some planes are kept in a holding pattern longer than others.

Those documents with drop-dead deadlines for submission to government regulators by a particular date are like aircraft that have flown across the Pacific and are low on fuel — they get priority, while the others remain in a holding pattern until the deadline ones have cleared the runway.

Cabin housekeeping

If you’ve ever taken a long-haul flight, you may recall the state of the cabin when you finally disembarked the plane — it’s pretty awful. And you may have felt for the cleaning crew who have a limited time to turn it around before the plane takes off again. Some documents are like that. When I open a document for the first time, I may be confronted with an absolute mess of styles, document automation that’s gone wrong, formatting that’s all over the place, cross-references and captioning that aren’t automated, tracked changes from months ago that have still not been dealt with, etc. Like the cabin cleaning crew, I can’t make the document ready for editing until I sort out the mess and clean it up. So my first task when I get a new document from an author is to run my long list of formatting passes over it — apply the correct template, sort out the document automation, apply the correct styles, accept all field update track changes etc. Only when it’s ‘clean’ can I get on to the reading stage of the editing. Just like the cabin maintenance crew can’t refurbish the supplies (pillows, blankets, headphones, catering, etc.) for the next flight until the cleaning has been done.

Take off and landing

I’ve flown on the A380 several times. It’s a huge lumbering beast and it seems to defy all laws of physics to take off. When you’re taxiing down the runway, you don’t think it will ever get off the ground — and it seem to take an age to do so. Some documents are like that. The formatting stage takes far longer than I expect on first glance, so it’s half a day (or more) before I can ‘take off’ and get started on the editing (the formatting stage typically takes between 15 minutes and two hours, so half a day is long for me).

The final stages of my editing involve finalizing the terms list and the references list. And here the final approach and landing can get very bumpy if the author has not followed our guidelines for citing and referencing documents in their document. What should take only a few minutes can take several hours, thus delaying the delivery of the document (late arrival).

Plane type

The A380 has a LOT of bells and whistles, especially when compared to a little puddle jumper. While all the documents I work on have the basics, some documents — like the A380 — are full of bells and whistles, incorporating not only a table of contents, but also lists of tables, figures, and plates, multilevel outline numbering, several bullet list levels, many appendices, portrait/landscape orientation, complex tables, many figures, various page sizes (A4 and A3 mostly), track changes, comments, different highlighting colors for different things the author still needs to address, many section breaks, etc. Like the A380, these are lumbering beasts.

****

Since that conversation, I’ve started to think about my documents as plane flights — it makes for some interesting insights!

I’m sure there are other ways that editing is like flying — feel free to add your comments.

h1

Sony Xperia Tablet Z: WiFi connection issues

August 21, 2013

It took a while, but I’ve finally joined the tablet generation ;-)

I actually got my Sony Xperia Tablet Z a couple of weeks back (and I love it!), but as I’ve had issues with continual WiFi connection dropouts, I didn’t want to say much. After the first few days of frustration, I went searching to see if others have had similar issues with WiFi disconnections — and they had. Not everyone, but enough. I followed various options to adjust the settings on my tablet, all to no avail (see the forum posts below).

I also called Sony Support in Australia and they got me to force reset the operating system. Fortunately I didn’t have much on the tablet as this reset/reinstall wiped EVERYTHING (despite me thinking that the backup process I initiated beforehand had actually worked…). I had to download and reinstall all my apps and set up my connections to Outlook Exchange Server etc. But still the WiFi continued to lose connection, even when I was sitting within one metre of the router and the signal was reporting as ‘Excellent’.

Work took over for another week or so, but I finally called Sony Support again yesterday to tell them that the reset hadn’t worked and to ask when the Android 4.2.2 OS would be rolled out to the WiFi-only tablets like mine, in case it helped (I didn’t get an answer to that, BTW). I told Aaron — the helpful guy at Sony — that I’d contacted my PC support people and they’d changed a setting on the router from b,g,n wireless to b,g, but that didn’t work (I changed it back), and that I was already on Channel 6 (i.e. a channel less than 11). I also told him I was loathe to update the firmware on a router that worked fine for absolutely everything else (the WiFi connection for my phone and laptops in the house is fine, and I don’t want to mess with my VPN settings as I’ve got some very critical work coming up in the next few weeks).

Aaron suggested that I try connecting to a local free WiFi hotspot (yeah, but for me that involves a 50 km round trip to get to one!) and see if it still drops out as he suspects it’s the router. But I can’t do that for a while. So meantime, he suggested a free Google Play app, called WiFi Static. He said others with similar issues on their phones etc. had had some success with it, though he couldn’t guarantee anything.

I downloaded and installed the WiFI Static app yesterday, and while I’ve had a couple of dropouts, mostly the connection has remained very stable. Stable enough for me not to get continually frustrated at having to reconnect, which was what was happening before. I’m only on day two of using WiFi Static, and have only had to reconnect about three times. Prior to installing WiFi Static, I would’ve had to reconnect about 20+ times in the same time period.

So if you’re having similar issues, try WiFi Static. It may work for you too.

Once my critical period at work is over, I’ll investigate updating the firmware on my router.

BTW, I don’t have Bluetooth enabled on this tablet yet, so that’s not creating any sort of conflict (for some people on the forums, Bluetooth was a critical factor).

Update one week after the original post: WiFi Static seemed to work fine for a few days, but then I started getting the connection drop-out issues again. Nowhere near as bad as my original experience, but still annoying. On someone’s advice, I also installed the WiFi Analyzer app, which shows which of the channels are good, the strength of the WiFi, available networks etc. It didn’t seem to make any difference, but it was interesting viewing the stats and performance graphs etc.

Update 6 September 2013: Earlier this week, Sony rolled out the Android 4.2.2 update to my tablet. I installed it and wanted to see if it made any difference to the WiFi connection issue. It seemed to, but I wanted to wait several days before jumping to any conclusions. Those several days are now up and I can confirm that I’ve had NO WiFi disconnections since that update was installed. None. Nada. Zip. Whether it was something that changed in Android, or something that Sony changed in the rollout, I don’t know. All I know is that my WiFi connection issues seem to be gone… so far! Further update 1 November 2013: I haven’t had a single connection issue since the upgrade to Android 4.2.2, so it’s all good.

Connection symptoms I had

I had any one or all of these messages when I lost connection:

  • No internet connection
  • Authentication problem
  • Saved, secured with WPA
  • Disconnected

And the signal strength made no difference — I would get these dropouts when the signal was ‘poor’, ‘good’, and ‘excellent’.

Sometimes it would reconnect automatically if I started using the tablet again after it was asleep; sometimes not. Sometimes it would reconnect and hold connection for some minutes, even an hour or so, when I manually forced the reconnect; sometimes it took 4 or 5 attempts before I could reconnect, and then it might only hold for about 30 seconds.

Forum discussion threads that may be of use

[Links last checked August 2013]

h1

Dealing with abbreviations, acronyms, and initialisms

August 19, 2013

Based on a writing tip I recently sent to my work colleagues.

NOTE: These are the rules based on our style guide and its referenced authorities. Your style guide may differ.

*******************

In accordance with [our style guide]:

  • Always write out in full any abbreviation/acronym/initialism (see Notes for the differences) the first time you use it in the main body of the document, then put the abbreviation in parentheses; e.g. Materials Offloading Facility (MOF). Exception: Do not write out in full common abbreviated measurement units (e.g. km).
  • After that first instance, you can use the abbreviation etc. (e.g. MOF) throughout the rest of the document, except in the References list (see Other Guidance below).

OTHER GUIDANCE:

  • Don’t use punctuation between the letters of an acronym or initialism (e.g. CSIRO, not C.S.I.R.O.).
  • If the term is only used once or twice in the document, you probably don’t need to abbreviate it, unless you know your readers are more familiar with the abbreviation (e.g. GPS, PPE), in which case write it in full the first time with its abbreviation even if it’s only used once in the document.
  • If a term is used more than about five times in the document AND there’s an abbreviation for it, consider replacing the term with the abbreviation. But first consider your audience (e.g. some regulatory documents may want certain terms written in full every time).
  • If the term and abbreviation are first used inside parentheses (such as in a citation), then use square brackets for the abbreviation within the parentheses; e.g. ‘blah blah (Department of Environment and Conservation [DEC] 2007) blah blah’.
  • In the References list, write out the abbreviation etc. in full where it’s the authoring body or the publisher (e.g. ‘Department of Sustainability, Environment, Water, Population and Communities. 2012.’ not ‘SEWPaC. 2012.’)
  • Make sure all abbreviations etc. you use in the document are listed and defined in the Terms list. You still have to write each term in full the first time it’s used in the main body of the document.
  • If the term is capitalised (capped) because it’s the proper name of something (e.g. Materials Offloading Facility), then keep those capitals in the full version, but if the term is normally not capped (e.g. personal protective equipment), then only use caps in the abbreviation (e.g. PPE).
  • Follow the guidance for SI units for the abbreviation and capitalisation of units of measure; e.g. km/h not km/hr (see  http://www1.bipm.org/utils/en/pdf/si-brochure.pdf [especially the tables in Sections 2.1.2, 2.2.1, 2.2.2, and 4.1 of that document]).

NOTES (from http://grammar.quickanddirtytips.com/acronyms-grammar.aspx):

  • Initialisms are made from the first letter (or letters) of a string of words, but can’t be pronounced as words themselves. Examples include FBI, CIA, FYI (for your information), and PR (public relations).
  • Acronyms are made from the first letter (or letters) of a string of words but are pronounced as if they were words themselves. Examples include NASA, NIMBY (not in my backyard), and hazmat (hazardous materials).
  • Abbreviations are any shortened form of a word.

*******************

h1

Common image sizes for social media

August 13, 2013

I found this in a quilting magazine and figured it was useful to share — it lists the common images sizes for profiles, avatars, and banners for each of the main social media and sharing platforms.

profile_pics

(From Quilting Arts Magazine, April/May 2013, Issue 62, page 17)

Update July 2014: A more recent one is here: http://blog.mainstreethost.com/social-media-image-size-cheat-sheet (click to view full size):

Social Media Image Size Cheat Sheet
Courtesy of: Mainstreethost’s Blog

 

[Link last checked July 2014]

h1

Word = chocolate!

August 10, 2013

I helped AJ in the Netherlands solve a tricky Word problem via Skype Chat the other day. Look what she sent me! All beautifully packaged in a wooden box, and sent from Sydney.

I like the equation: Solve a Word problem. Get chocolate as thanks. ;-)

Thanks AJ!

thanks02

thanks01

h1

Book review: Planning and Structuring User Assistance

August 6, 2013

Details:

************************

This was the second book I read from Marc Achtelig’s Technical Documentation Solutions Series. Like the first one I read (‘Designing‘), it was well-written in plain, simple language, and was laid out in such a way that I could dip in and out of it and use it as a reference book. While I read it from cover to cover for this review, I would expect that most readers would use it as a reference as each topic can stand alone.

Marc states that the intended audience for this series of books are:

  • full-time technical writers
  • developers, marketing professionals, and product managers who occasionally write some technical documentation
  • designers who create templates for user manuals and online help systems
  • multimedia experts who create screencasts, tutorials, and e-learning courses.

In my opinion, this Structuring book is mostly for technical writers or anyone else involved in writing product documentation (software or hardware).

The topics covered are:

  • General structuring principles
  • Choosing media
  • Planning documents
  • Planning document sections
  • Planning topics
  • Planning the order of sections and topics
  • Planning navigation.

As with the first book, in the author’s note in Chapter 1, Marc talks about the rules for designing templates and my first reaction was ‘Whose rules?’ Different organizations, industries, and countries can have different ‘rules’, so I was concerned that Marc was going to focus on a particular set of ‘rules’ that were familiar to him, but not necessarily apply to everyone else. However, he surprised me by his ability to make solid generic recommendations that crossed all sorts of boundaries and therefore that could apply to most situations.

In this book he starts straight in on what he calls the ‘universal principles’; specifically:

  • Don’t try to please everybody
  • Make it goal-centered (‘it’ being the document, topic, section etc.)
  • Layer information
  • Split complex information
  • Find the right amount of redundancy.

And further: ‘A user-friendly structure should reflect:

  • the tasks and goals of your primary user group
  • the information needs of your primary user group
  • the mental model of your primary user group’

I particularly liked the inclusion of ‘mental model’ in this list as I think it’s an aspect that often gets lost when we are defining who are users are.

And I LOVED this (p64-65):

What you shouldn’t include at all (in the preface):

  • Don’t congratulate users on choosing or buying your product. Most users don’t read manuals before using a product. They only read a manual when they have problems. Congratulating them in a situation like this may sound cynical and doesn’t add any information and value to your document. Phrases like this just stand in the way of the real information.
  • Don’t say that you’re pleased that users chose your product. Users don’t care about your feelings.

Note: It’s perfectly OK and important to build up a positive attitude toward your product. However, do so by providing value rather than words. Give users a reason to love your product and its documentation rather than telling them how wonderful both are.

Most of the notes I took as I was reading the first book also applied to this one, plus a few more specifically for this book:

  • Nice clear writing, with practical examples.
  • Excellent coverage of the basics and the do’s and don’ts. Good examples.
  • Excellent refresher for experienced practitioners; great advice for beginners.
  • Offers advice/rule and clear reasons for doing/not doing it.
  • All diagrams were clear and simple and got the message across successfully.
  • In this book he emphasizes the human touch required for indexing, and advises staying away from the automated indexes created by authoring tools; this is in direct contrast to what he said in the Designing book, and is a recommendation I agree with.
  • Unlike his Designing book, this one focuses more on online help.
  • Very comprehensive.

I only had a few negative comments about this book:

  • As with the first book, I read a PDF version of this book on an Android tablet (via Adobe Reader). There were some issues with odd artefacts in the PDF, e.g. single and double quote marks, en and em dashes all rendered as odd characters. This should have been checked/dealt with when the author verified the PDF output from their single-sourcing authoring tool as there were far too many for it to be an odd occurrence. UPDATE: The author sent me a couple of revised versions with different Adobe settings and one of those worked very well, with no artefacts displayed at all. He assured me that he had embedded the fonts and checked the display. If nothing else, this has shown that the same software on different platforms and different devices may render the text differently.

Overall, this is an excellent guide to planning and structuring electronic and printed product documentation. It is suitable for beginners and experienced practitioners alike.

I’ll leave the final word to Marc:

When deadlines are close and budgets are tight, it’s better to provide medium quality information but excellent navigation than to provide excellent information but poor navigation.

h1

Book review: Designing Templates and Formatting Documents

August 5, 2013

Details:

************************

This was the first book I read from Marc Achtelig’s Technical Documentation Solutions Series, and I look forward to reading others. Why? Because it was well-written in plain, simple language, and was laid out in such a way that I could dip in and out of it and use it as a reference book. While I read it from cover to cover for this review, I would expect that most readers would use it as a reference as each topic can stand alone.

Marc states that the intended audience for this series of books are:

  • full-time technical writers
  • developers, marketing professionals, and product managers who occasionally write some technical documentation
  • designers who create templates for user manuals and online help systems
  • multimedia experts who create screencasts, tutorials, and e-learning courses.

In my opinion, this Designing book is also for the person in a small company who has to set up templates for others to use; for example, an admin assistant. While the sections related to online help wouldn’t apply to them, those on page layout, etc. would.

The topics covered are:

  • Layout
  • Type area
  • Fonts /spacing
  • Screen layout
  • Page layout
  • Table design
  • Paragraph styles
  • Character styles

In the author’s note in Chapter 1, Marc talks about the rules for designing templates and my first reaction was ‘Whose rules?’ Different organizations, industries, and countries can have different ‘rules’, so I was concerned that Marc was going to focus on a particular set of ‘rules’ that were familiar to him, but not necessarily apply to everyone else. However, he surprised me by his ability to make solid generic recommendations that crossed all sorts of boundaries and therefore that could apply to most situations.

The other thing that surprised me was Marc’s ability to talk generically about authoring tools, yet not mention a single tool. But in no way did that detract from the information he provided — in fact, it enhanced it as he didn’t get caught up in what Word could do versus FrameMaker, versus RoboHelp, versus Flare, versus Author-it, versus any other authoring tool you might want to name.

Here are the notes I took as I was reading this book:

  • Nice clear writing, with practical examples.
  • Excellent coverage of the basics and the do’s and don’ts. Good examples.
  • Excellent refresher for experienced practitioners; great for beginners.
  • Offers advice/rule and clear reasons for doing/not doing it.
  • Lots of advice on setting up templates, without referring to ANY authoring tool — a remarkable achievement.
  • All diagrams were clear and simple and got the message across successfully.
  • While online help is dealt with, the book would be ideal for anyone setting up a document, not just technical communicators. Ideal also for those new to the profession.

I only had a few negative comments about this book:

  • While I found the advice to use keyboard shortcuts and meaningful names for paragraph and character styles useful, I found the style name examples he gave quite unconventional (in my experience) and against the author’s advice to use style names that were easy to interpret and remember.
  • I disagreed with his assertion that ‘most Help authoring tools create a well-designed index automatically’. This has NOT been my experience, and a competent author/indexer is needed for a useful index, otherwise it’s just a list of topics or words used, without any weight given to their importance or their contextual use.
  • I read a PDF version of this book on an Android tablet. There were some issues with odd artefacts in the PDF, e.g. single and double quote marks, en and em dashes all rendered as odd characters. This should have been checked/dealt with when the author verified the PDF output from their single-sourcing authoring tool as there were far too many for it to be an odd occurrence. Perhaps he didn’t follow his own advice on font selection and embedding… UPDATE: The author sent me a couple of revised versions with different Adobe settings and one of those worked very well, with no artefacts displayed at all. He assured me that he had embedded the fonts and checked the display. If nothing else, this has shown that the same software on different platforms and different devices may render the text differently.

Overall, this is an excellent guide to designing electronic and printed document templates, suitable for beginners and experienced practitioners alike.