Archive for October, 2012

h1

Tightening your writing

October 26, 2012

Based on a writing tip I wrote recently for my work colleagues.

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

This Writing Tip focuses on ways you can tighten up your writing by removing words and rearranging words. The examples below are from some documents I’ve edited recently. Note that some of these examples swap a word for its plain language alternative (see Gobbledygook, Jargon, and Plain Language).

Bottom line:

  • Watch for the excessive use of ‘of’. You can often remove ‘of’ without affecting the meaning of the sentence – if you see an ‘of’ try reading the sentence without the ‘of’ and if it still makes sense, then delete ‘of’.
  • Don’t follow these guidelines blindly. The context is important, and what you’ve written may be correct for your context.

Let’s look at some examples from some documents I’ve reviewed:

Instead of… Try this…
report on an annual basis report annually
report on a monthly basis report monthly
on a regular basis regularly
the frequency at which how often
in the event of if
There were no [xxx] recorded No [xxx] were recorded
has been OR have been was OR were (depending on context)
until such time as until
employ use
utilise use
in excess of more than OR exceed
outside of outside
comprises of comprises
is comprised mostly of mostly comprises
are comprised of comprise
This section seeks to define This section defines
When communicating, it is important to select the most appropriate method or way of communicating to achieve your goal or objective. Select the most appropriate communication method to achieve your goal or objective.
ascertain check
It is a requirement to wear full PPE… You must wear full PPE…
carried out in a safe fashion carried out safely
working in a safe and productive fashion working safely and productively
is presented/provided/given in Figure x.x is shown in Figure x.x
The [xxx] Archipelago is an area encompassing 42 islands… The [xxx] Archipelago encompasses 42 islands…
a spill of 700 m3 of diesel a 700 m3 diesel spill
summer season summer
testing of [xxx] testing [xxx]
methodologies methods
the majority most
restricted access of fishing restricted fishing access
mortality death
measurements of the noise noise measurements
from the installation processes themselves from the installation processes
took into account considered
on the other hand whereas
will be managed through will be managed by
The environmental impacts of the spill are dependent to a large degree on The environmental impacts of such a spill largely depend on
by way of comparison compared to
report on and include a summary of report on and summarise

The first column used 178 words (874 characters, not including spaces), while the second column used 111 words (622 characters, not including spaces). So in addition to making the text more readable and understandable, the alternatives require less typing (and less paper if printed).

See also:

h1

ASTC (NSW) annual conference

October 24, 2012

Next week I fly to Sydney to attend and speak at the annual ASTC (NSW) conference (conference details here: http://astcnsw.org.au/training-and-events/conference/conference-2012-emerging-and-evolving/).

I’ve presented at this conference before, in 2006 and 2008. It’s a smallish conference with a single stream of presentations, so everyone gets to know each other. Of course, many of the NSW people already know each other, but for speakers like me who come from further afield, it’s good to be able to put faces to names and to meet most of the participants.

This year I’m doing two presentations, one on editing and one on working from home (telecommuting).

My good friend Dave Gash is coming over from the US to speak at this conference too (after speaking at the TCANZ conference in NZ this week), and Hamish Blunck is also speaking. Hamish and I have had quite a few phone conversations and email discussions over the years, and he was my replacement at a Brisbane-based company I worked for. Despite all our connections (we also follow each other on Twitter), Hamish and I have never met, so it will be good to meet him.

I’m also looking forward to catching up with ASTC (NSW) members whom I’ve met at previous conferences.

My thanks go to Janet Taylor who has been my liaison for the conference — her organizational skills have been invaluable in making this all happen.

h1

Gobbledygook, jargon, and plain language

October 19, 2012

Based on a writing tip I wrote recently for my work colleagues. The industry is oil and gas. And yes, I know that ‘bottom line’ qualifies for Buzzword Bingo ;-)

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

Bottom line:

  • Use plain language where possible so the reader doesn’t have to try to figure out what you mean.
  • Consider how you would explain the concept to your parents, children, grandparents, those who don’t work in the industry etc. – and then use that language in your writing. Plain, simple, and easily understood.
  • Every time someone has to stop and think while reading your document, the organisation incurs a cost – time, lost productivity, rework etc.
  • Every misinterpretation could put a life at risk.

Let’s look at some examples from some documents I’ve reviewed:

Phrase as written by the author My comments
‘Each sub-phase will be reviewed and assured prior to proceeding to the next sub-phase.’ What does ‘assured’ mean in this context? None of the dictionary meanings fit how it’s used in this sentence. Does it mean ‘confirmed’, ‘approved’ or something similar? If so, use one of those words so that the reader isn’t confused.
(By the way, the Macquarie Dictionary definitions for ‘assured’ are:

1. [adj] made sure; sure; certain.

2. [adj] bold; confident.

3. [noun] boldly presumptuous.

None of these really fits the sentence, though I suspect a variation of the first definition is the closest.)

‘could leverage synergies with’ This one would qualify as a BINGO! in Buzzword Bingo (see links below). Consider using plainer language, e.g. ‘take advantage of’, ‘cooperate with’, ‘combine with’, ‘joint opportunity’ etc.
‘to enable performance characterisation of the…’ More business jargon and another candidate for Buzzword Bingo. What does ‘performance characterisation’ mean? How would you explain this to your parents, for example?
‘does not contain a sufficiently large portion’ While the individual words are in plain language, ‘sufficiently’ and ‘large’ are relative terms. What does ‘sufficiently large’ mean in this context? Larger than what? How ‘sufficient’ does it have to be to be ‘sufficiently large’? Either be specific about the size of the portion (using a value and unit of measure) or reword.

For each example listed above, I had to stop and think, try to figure out (guess!) what the author meant, consult the dictionary, or do all these actions. Each hesitation was a distraction that took my focus away from my objective of reading and understanding the content. Each time I searched the dictionary or thesaurus and tried out alternative words in my head, my focus was off the document and onto something else. Instead of reading a paragraph and knowing straight away what it meant, I was distracted – and sometimes confused. Thus the time I took to read and understand the sentence, paragraph, entire document was compromised. And that’s just me. Multiply that lost time by the number of readers of your documents who don’t understand what you mean and thus have to try to figure it out and now there’s a much bigger issue than just a silly word or two.

Let’s say your document is read by 30 people, and each person ‘loses’ just 10 minutes on that one document trying to understand what you’re saying. That’s a business cost of 300 minutes (5 hours) to the organisation for ONE document—a cost that could have been prevented if you’d spent just an extra minute or two converting gobbledygook and business jargon into plainer language. Multiply that over the thousands of documents produced and read by thousands of employees and contractors per year and now you’re looking at a substantial cost to the organisation.

But potentially there’s an even bigger business cost than lost time, and that’s the cost of misinterpretation. Sure, for many documents misinterpretation of a single word or phrase doesn’t matter too much. But ours is an industry [oil and gas] where lives may be at risk if an instruction is misinterpreted, or if a specification uses an incorrect unit of measure (e.g. inches instead of centimetres, grams instead of milligrams) or doesn’t specify a measure (‘sufficiently large’), or if a comma is in the wrong place thus making a sentence ambiguous and open to misinterpretation.

Loss of life, law suits, government inquiries etc. are all potential costs of misinterpretation.

So, after you write a sentence/paragraph/section/document, read it through before finalising it to make sure that all the words/phrases you use will be understood by your target audience. If in doubt, think about how you’d explain it to someone outside the industry and use those words instead. Or get someone else to read it and alert you to anything they can’t understand or that they hesitate over.

See also:

And for fun:

[Links last checked October 2012]

h1

Acrobat: Setting permissions on a PDF document

October 18, 2012

One of my clients asked:

I am saving a PDF file for registered users to download. I’ve set the settings so that people will not be able to edit the information. What other things should I be setting? Author’s details? I have no idea where that is located.

Here’s my response, with some instructions; .

I guess your main purpose in protecting the PDF is to prevent unauthorized copying and modifying, and to indicate authorship.

  1. Open the PDF in Acrobat Pro (these settings are the same in Acrobat 9 Pro and Acrobat X Pro, the two versions I tested).
  2. Go to File > Properties.
  3. Description tab: This picks up the title and author from the originating document (e.g. Word), but you can change that information here. Title and Author would be the main ones – personally, I don’t think you need to bother with the rest. That said, under the Additional Metadata button there are some copyright options. These don’t DO anything, expect add information that you provide about copyright. Be aware that ANYTHING published in Australia is automatically subject to copyright law, whether you have a © imprint/details proclaiming copyright or not.
  4. Security tab: Here’s where you can lock down your PDF. But be careful about locking it down too much. You may want to consider locking down Content Copying and Changing the Document.
  5. On the Security tab, go to Security Method and select Password Security. The Password Security — Settings dialog box opens.
  6. Go to the Permissions section of the Password Security – Settings dialog box and consider selecting Restrict editing and printing, then select one of the Printing Allowed options and Changes Allowed options.
  7. Consider turning off the Enable copying of text, images and other content check box, and consider leaving the Enable text access check box turned on.
  8. Add a password in the Change Permissions Password field (in the Permissions section). Make sure you note this password somewhere otherwise you won’t be able to copy the content etc. either. (Of course, you could always re-create the PDF from the original document if you forget the password.)
  9. Click OK to close this dialog box.
  10. Click OK on the warning message.
  11. Enter the document’s password you just set at Step 8 on the password confirmation popup box, then click OK.
h1

Cross-references

October 15, 2012

One of my colleagues asked me some questions about cross-references.

But first, a bit of backstory…

We’re preparing a very large Word document (800+ pages) and each Section (about 18 of them) is being prepared by a different author. At some point, I will have the job of bringing these individual Sections (aka chapters) together into one BIG Word document prior to it going out to the printer and prior to it being PDF’ed and put online for public distribution and comment. I’ve designed the Word template and the styles to make this job easier; I’ve tested the process of compiling the document’s Sections; and I’ve documented the ‘gotchas’ I’ll have to watch out for.

In the meantime, the authors have been beavering away on their Sections. One of the ‘best practice’ things they’ve been doing is inserting automated cross-references for tables, figures and subsections WITHIN their Section, and inserting plain text Section/subsection/table/figure numbers and captions/headings for what will eventually be automated cross-references to other Sections once the document is a single document. It will be my job to create the automated intra-Section cross-references.

But there must have been some discussion in the office about the number of these cross-references to other Sections — perhaps authors were finding it cumbersome to add them, perhaps they were concerned about the readability of the document when it was peppered with cross-references within the text. Maybe something else. So my colleague contacted me to get my advice.

Here’s a summary of my response:

  • Consider WHY you have a cross-reference (x-ref) to another section, table etc., whether it’s to something in the same Section or in a different one. The bottom line is that x-refs to a Section/subsection help you avoid repeating the same information in multiple places, or refer to a table/figure that follows or has gone before that provides the information the reader needs to make sense of the narrative.
  • Consider HOW a reader will approach a x-ref. In print, they have to flick the pages to find the supporting information, but in online (PDF) they only need to click the link to go to the relevant part to read the information, then can click back to return to where they were. Clicking a link is a simple process for the reader, though going back in a PDF is not quite as straightforward. (See my blog post about this from 2010: https://cybertext.wordpress.com/2010/07/06/acrobat-back-and-forward-buttons/)
  • Consider WHEN to insert a x-ref or not. If the reader MUST know about something that’s gone before or is to come (e.g. Section 8 Assessment Method) to properly inform the current section, then a x-ref is necessary. Likewise, if the data that supports a claim is held in a table or figure, then a x-ref to that table/figure is necessary. However, if the x-ref is a ‘nice to have’ and just offers a link to related (but not essential) information for the reader, then the author has to decide whether to include it or not.
  • Consider WHERE to insert a x-ref. Essential x-refs to other Sections and to tables/figures should go as close as possible to where the referring information is written (which is what you do now). However, for the ‘nice to have’ related x-refs that aren’t essential, consider whether breaking them out into a sidebar/box/list at the bottom of the Section/subsection might be more useful to the reader than peppering them throughout the narrative. If you do pursue this option, make sure the [government regulators] are happy with the idea first and that there’s nothing in the requirements documentation that prevents you from doing so. Also, I suggest you test it on a single Section to see how easy/hard it is to do and how convenient/awkward it is for a reader to deal with.
  • Consider WHO will read the document and HOW they will read it. Some readers of the doc will only focus on one or two Sections (e.g. the Department of Fisheries might only focus on marine Sections and ignore terrestrial fauna sections), while others may read the entire document. For a reader who has a limited focus, you cannot assume that because they are reading Section 9 that they’ve read the preceding Sections 1 to 8; even for readers who read the entire document, you can’t assume that they’ve read and remembered what was said in earlier Sections.
  • Please DO NOT consider converting the existing automated x-refs into manual ones. There be dragons… Future updates to the documents (e.g. insert/delete a subsection, table/figure) would mean that existing references to subsection numbers, table/figure numbers would be out of order and it would be a nightmare to try to find and fix them all. Automated x-refs mean that you can add/delete material without upsetting the links.

Ultimately, knowing who the likely reader is for this document and how they will access the document will dictate the direction my colleague will take. After all, such a document is about the reader, not the writer, so whatever is easiest for the reader to deal with should prevail over any ‘it’s too hard’ issues that the authors may have.

See also:

[Links last checked October 2012]

h1

Cryptic error message

October 12, 2012

I tried to go to a web page and got this message instead:

A classic example of a meaningless (to this reader anyway) error message.

According to Wikipedia, a 503 error message is:

503 Service Unavailable The server is currently unavailable (because it is overloaded or down for maintenance). Generally, this is a temporary state.

So why couldn’t this message say that? ‘No healthy backends’, ‘guru meditation’, a cryptic XID number (whatever ‘XID’ is), and ‘varnish cache server’ mean ABSOLUTELY nothing to me.

But ‘server overloaded or down for maintenance’ does mean something. Some plain language training wouldn’t have gone astray for the person who wrote this error message.

h1

PDF won’t deal with Word landscape pages properly

October 11, 2012

One of my work colleagues sent me a Word 2007 document and its resulting PDF and asked me to see if I could figure out what was happening with two landscape sections.

Both sections looked like this in the PDF, though they looked perfectly fine in the Word document — notice how the two pages with the maps have headers and footers going off the page and that the page is the same dimensions as the Portrait-oriented page above:

I tried several things — re-creating the PDF using Acrobat, using Word’s PDF option, fiddling with the settings in Acrobat etc. all to no avail. In fact, for some tests, I just made it worse!

So I decided to take a closer look at the Word document, and there I found the problem. What appeared to be a landscape section wasn’t. It looked like a landscape section and when I checked the Orientation options on the Page Layout tab in Word, it said it was Landscape, but when I opened the Page Setup dialog box, all was revealed.

The first thing I noticed was that Portrait was selected, not Landscape, even though Landscape was showing as selected on the Orientation button on the ribbon. WTF?

So I checked the Paper tab settings. One of the authors had set a Custom size for the paper size and defined a width and height that matched a landscape A4 page, thinking they were doing the right thing, but in hindsight they weren’t — it was a case of a little knowledge is a dangerous thing!

Just in case this custom page size was the cause of the odd PDF, I changed the page orientation setting on the Margins tab to Landscape.

I then went to the Paper tab to change it back to A4, but it had automatically changed to A4 after I switched to Landscape:

The next test was to save the document and re-create the PDF. The landscape section that was misbehaving now worked fine! So I changed the other incorrectly defined landscape section in the document and re-did the PDF.

Everything was right with my world again! ;-) And my work colleagues were very happy.

Actually, it wasn’t quite right… I found that the PDFs I generated had a lot of excess space above the headers and below the footers throughout the document no matter which PDF creation method I used. I only did a couple of tests to see what was causing it. But I just didn’t have the time to investigate, so I opened the document on my other computer in Word 2010 and re-created the PDF from the default settings and it worked — all that excess space disappeared. I still don’t know what caused that space issue — maybe I’ll have time to investigate the reason next week when some of my deadline pressure is off.

Update: The excess space above/below the headers and footers was related to the track changes view. The document had Final Showing Markup selected on the Review tab in Word as the authors need to show the readers the tracked changes. When I changed the view to Final and re-created the PDF, all that excess space above/below the headers/footers disappeared (as of course, did the excess space on the right for the tracked change markups). But of course, the track changes weren’t visible now. I know that most of the PDFs created by my client have track changes showing and DON’T have this issue with excess space about the headers/footers, but I haven’t yet figured out why it did it with this document. More investigation required…

Update 2: Gerald (comment 1, dated 18 Oct 2012 below) suggested turning off the balloons for comments and formatting in the Track Changes settings in Word. I did, and it worked — the excess space above the headers and below the footers disappeared! This was in Acrobat Pro X and Word 2007. On my other computer, I have Acrobat Pro 9 and Word 2010 and I didn’t get the excess space issue; however, on checking my Word 2010 Track Changes settings, I saw that they were set to show balloons Never, so it looks as though that’s the critical setting. That said, why does Acrobat add space above/below the headers/footers when the Word setting for the balloons is 6.5 cm right (or left; there are no options for top/bottom)? Interestingly, I used the ruler in the PDF to measure the space above/below and both were about 3 cm, so it looks as though Acrobat is not only adding a 6.5 cm space to the right to accommodate the comment balloons, but also adding a combined 6.5 cm to the length of the page too. As a side note, when I turned off the balloons, any comments in the document remained hidden in the PDF — there was a marker to indicate there was a comment, but the comment wouldn’t display in the PDF at all.