Working my way through 200+ pages of this…

A very small sample of some documentation I’m editing at the moment. Actually, I’m doing much more than editing it — I’m rewriting it. When you see the example below, you’ll probably understand why…

This is what the developers in another country wrote in the original admin guide:

DELETE LOOKUP VALUE: This button when clicked will update the selected string value, here we need to first select the value as the particular value will appear in the “New Lookup Value” text field and then required changes are made into the text field followed by a click on the “UPDATE LOOKUP VALUE” button and then hit on “Submit” button to permanently save the changes.

And this is how it now reads after I deciphered it (yes, they got it wrong too — they’d copied in what they wrote about the Update button into the information on the Delete button), tested it in the application, and rewrote it:

1. …
2. …
3. Select the lookup value you want to delete—it gets loaded into the New Lookup Value field.
4. Click Delete Lookup Value.
5. Click Submit.

I’ve only got another 100 pages of this to go….

Oh, and in addition to making it more readable, the text has gone from 65 words (372 characters) to 23 words (129 characters), an almost two-thirds reduction.

If this manual was to be translated, the savings in translation costs over those 200+ pages would be worth far more than what it cost my client to pay me to edit it.

Paying someone to edit your work pays off handsomely if you’re considering translation into another language, and these cost savings increase massively the more languages you have to translate to. A side benefit of editing is that you end up with readable and comprehensible text–you won’t annoy and anger your customers with turgid prose that they have to read several times over to figure out what it’s saying. If you re-read that original piece of writing, you can well understand why some people refuse to read manuals.

See also (from Sharon Burton):

• What customers are saying about product documentation — and why they are mad: http://www.sharonburton.com/consumer-feelings-about-product-documentation-results-are-in/
• Webinar recording on why customers get mad: http://www.sharonburton.com/recording-of-why-your-customers-are-mad-at-you/

[Links last checked December 2012]

Presentation: Editing: It’s not as easy as it looks

I delivered this 45-minute presentation on editing to the ASTC(NSW) 2012 annual conference on 2 November 2012.

The focus of this presentation was:

• the role of the edi­tor
• types of editing
• editing tasks
• the value of using check­lists and style sheets
• tools to auto­mate some edit­ing tasks (Microsoft Word add-ins, mostly)

The audience was technical writers and communicators who may only do editing as part of their usual role. (Please note: Some odd word wrapping occurred in some slides when I uploaded them to SlideShare — sorry about that!)

ASTC (NSW) annual conference

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.

I love my work colleagues!

This email (slightly modified to remove references to people, companies etc.) was sent to the entire team last week. I love working for these people!

Hi guys,

Just a quick reminder to not alter the formatting of the [ABC] document. This includes things like inserting new headers and footers (including for landscape pages), altering text styles and altering page numbers, etc. We have Rhonda as a great resource to make these changes and assist us with other formatting and authoring-based IT issues, not just the tech writing reviews she also does.

It’s not the best use of time as it takes us much longer to fiddle around in the formatting and styles than it will take Rhonda. Also often our best efforts to solve something in the document can cause more work for Rhonda to fix than the original issue.

Another way to think of it is, we have been hired for our technical expertise in environmental assessment, and Rhonda has been hired for her expertise in technical writing, document formatting and styles, etc.

Nice!

Do they grow the cotton first?

Oh dear. Typo in local newspaper this week:

Unfortunately, a person who sews can be called a ‘sewer’ (pron. so-er), but that can be easily misread as ‘sewer’ (pron. sue-er) as in the human waste disposal system.

It’s possible that the person who wrote this headline saw ‘sewers’ and thought it looked too much like the waste system, and thus changed it to ‘sower’, which has a totally different meaning altogether and means a person who plants seeds.

Further on in the copy, they got it right as ‘sewers’, but that headline was just plain wrong. If the headline writer wasn’t sure about ‘sewers’ then perhaps they should have reworded the headline to something like ‘Members come from far and wide’ or ‘National sewing guild AGM popular’ or similar.

Which reminds me..

When I attended a quilt workshop in Texas earlier this year, Laura Wasilowski did a ‘show and tell’ presentation where she told us about finding the tomb of the unknown sewer… ;-)

Tomb of the unknown sewer

[Photo from http://ww3.brevardcounty.us/usd/faq.cfm]

[Links last checked 25 July 2012]

Dinner with the editor

I loved this! ;-)

(from: http://www.creators.com/comics/6/78285_image.gif)

Visual edits: Power to the people

My colleague, JC, sent me these photos of a billboard advertising a new beachside housing development on some old industrial wasteland that is fronted by a dog beach (a place where owners can run their dogs freely). Over the past few years there have been moves by the local authority to shut down or shrink the size the dog beach, probably because the sight of dogs spoil the million-dollar ocean views from the high-rise apartments. The dog-loving residents have always turned out in mass protests, usually accompanied by local celebrities and the problem the goes away for another year or so.

JC said: “This morning I noticed this artistic edit to the large poster on the way to the beach. The original image had the boy running towards his ball lying on the sand. Now he is holding a yellow bag, which is the color of the dog droppings bag the City provides. The ball is now painted over with a silhouette of a dog doing what dogs do at dog beaches…”

Tooltip typo

I bet Australia Post didn’t get a technical writer/editor to check the tooltips on their website:

BTW, we spell it as ‘catalogue’ in Australia, so that’s not the error.

[Link last checked February 2012]

To cap or not to cap, that is the question

One of the team I work with asked:

Please could you provide us with some guidance on when to use and not to use capital letters. I would expect to use capitals for proper nouns, defined terms in a legal document, position titles, acronyms, symbols for chemical elements and the first word of each sentence. In most of the reports I read, almost every noun is capitalised and a smattering of other parts of speech as well. It looks like German.

Also:

What is the shortcut key combination for converting text to lower case?

Let’s get the easy one out of the way first…

To toggle the case of a letter, word, sentence etc, select it, then press Shift+F3 once, twice, or three times. Word will toggle between lower case (‘cat’), upper case (‘CAT’), and title case (‘Cat’).

Now on to the trickier issue of when to use initial capital letters (initial caps) or not.

The guidelines are clear for some things, but more fuzzy for others, especially when it comes how to treat generic and specific terms. The Australian Style Manual’s* index lists 20 page references specifically on capitals, with another 31 page references for the 21 index subentries under ‘capital letters’! There’s no way I’ll reproduce those guidelines here, but I’ll attempt to summarise them.

The Australian Style Manual (p119) has these overarching principles:

• Sentences should always start with a capital letter.
• Initial capitals should be used for proper nouns and proper names (i.e. the names of people, places, and organisations).
• When organisations’ names are reduced to a generic element, the capitals can usually be dispensed with; however, capitals are [kept] if the shortened version still carries a specific element. Thus, the Attorney-General’s Department becomes ‘Attorney-General’s’ [or] ‘the department’.

They also make the comment that ‘One of the few remaining widespread uses of capitals to distinguish an otherwise generic word is found in legal documents, where words that have been specifically defined (such as ‘Schedule’, ‘Party’, ‘Company’, ‘Owner’) are often capitalised wherever they appear.’

When in doubt, consult your corporate style guide, a published style guide (like the Australian Style Manual or the Chicago Manual of Style), or your dictionary.

Note: This summary was written for MY team and is based on the Australian Style Manual; your style guide may differ on some of these.

Use an initial capital for…	Example	Notes/comments
The first word in a sentence	All personnel must… A risk assessment was… The stakeholders agreed…	Only exceptions: names deliberately spelled in lower case; business names built on internet addresses; trade names with mid-word capitals such as ‘eBook’
Titles and honorific names	Minister, Professor, Doctor
Personal names	Jim Jones, Mary Smith
Nationalities and distinct groups of people, religions, languages and language groups	Aboriginal, Chinese, American, Australian, Hindu	Exceptions: common words derived from geographical locations (e.g. brussels sprouts, venetian blinds)
Official names of organisations (includes companies, government departments, states etc.)	Department of Environment and Conservation, Shire of Ashburton, Government of Western Australia, XYZ Project	No caps for the generic element of these names, e.g. the department, the shire council, the council If some specificity remains (even if only implied), capitalise the specific elements, e.g. a matter for the Shire, a matter for the Department, a matter for the State government, Project-related Always use the capitalisation, spelling, and punctuation that the organisation uses
Commonwealth		ALWAYS capped when referring to the Commonwealth of Australia Note: p124–125 of the Style Manual deals specifically with all government terms and their capitalisation
Acts, Regulations, Agreements	Environmental Protection Act 1986 (WA) National Greenhouse and Energy Reporting Regulations, 2008 Republic of Korea–Australia Migratory Birds Agreement	All main words of these are capitalised (title case) Acts are always italicised; Regulations are in normal text
Geographical locations (place names)	Barrow Island, Dampier, Perth, Western Australia, Pilbara, Great Barrier Reef	Exceptions: Descriptive, unofficial names for parts of a geographical entity usually don’t get capped, e.g. northern Australia; spelled out points of the compass, e.g. south-west Note: The WA Geographic Names Committee recommends (Section 4.12) that apostrophes are not used in geographic names that are named after people (e.g. St Georges Tce, NOT St George’s Tce).

Months and days	January, Monday	Exception: names of seasons, e.g. summer, winter
Taxonomic groupings down to genus level	Blattodea Blattidae, Blatta Myrtles, Myrtaceae, Eucalyptus	Species, subspecies, varietal names are NOT capped Note: Genus and species levels are italicised, as are subspecies and varietal names
Common names of specific species	Humpback Whale, White-winged Fairy-wren, Spotted Dolphin, Silver Gull, Flatback Turtle	Exceptions: common generic names of plants and animals are not capped, e.g. mammals, spiders, fish, corals, marine turtles See the WA Museum nomenclature for correct hyphenation, capitalisation
Abbreviated chemical names	CO2, H2S	Not capitalised when written in full, e.g. carbon dioxide, hydrogen sulfide
Personal name element of cyclones	tropical cyclone Carlos	Note: The personal name is capped, but NOT the preceding generic element (‘cyclone’, ‘tropical cyclone’)
Registered trademarks, proprietary names, brand names, computer software and hardware	Caterpillar, Toyota Land Cruiser, Microsoft Excel	Follow the capitalisation, spelling, and punctuation used by the owner
Title of books, journals, articles	Marine Ecology Progress Series	Follow the capitalisation used for the publication. In some cases it will just be the first word; in others, title case will be used, where every main word is capped
References to certain elements in a publication	Section 4.0, Figure 3.2, Chapter 9, Table 5.3	Don’t capitalise ‘pages’ (e.g. pages 23–56, NOT Pages 23–56)
Abbreviations, initialisms, and acronyms	HDD, LNG, WA	The spelled out version should obey the rules regarding proper nouns/names, so in many cases, the spelled out version is in lower case (e.g. horizontal directional drilling, liquefied natural gas, Western Australia)
Headings and captions	Sea-finding Behaviour of Marine Turtle Hatchlings	Use title case for all section headings, figure and table captions. Title case capitalises every main word, but not the ‘little’ words such as on, by, for, of, the, an, a, for, etc. Do not capitalise the second word in a hyphenated word

After colons	Note: All deliverables…	Only necessary where one or more full sentences or questions follow the colon. Otherwise, use lower case. Exception: capitalise the first word after ‘Note:’
Items in a table		First letter of each item in a table cell is capped Exception: units of measure, such as ‘metre’, that would not normally be capped
Units of measure	C, J, kg, km, m	Only some are capped; most are lower case, but there are some exceptions. See lists of SI Units for correct capitalisation Time: ‘am’ and ‘pm’ are lower case and separated from the hours/minutes by a space (e.g. 10:00 am)
Bullet lists		Follow the rules for sentences – if ALL bullet points in the one list are full sentences, cap the first words of each; otherwise, lower case for the first word of a sentence fragment (unless it’s a proper noun/name)
Job titles	Environmental Team Lead, Managing Director, Senior Engineer	Generic job titles are not capped (e.g. fitters, plumbers, electricians, project managers, administrators, team leads), but specific job titles associated with an individual are capped (e.g. Environmental Team Lead, Managing Director, Project Manager). Hint: Is the title plural or singular? Plural usually indicates that it’s generic; singular indicates it’s specific to an individual
Hyphenated terms		Depends on whether it’s used as the first word in a sentence (cap first word only) or in a heading (cap first word only) or in the body of a sentence (don’t cap at all unless a proper noun/name). Second word of a compound hyphenated term is rarely, if ever, capped (unless a proper noun/name)
Names of buildings, structures, locations etc.	Crib Room 3, Construction Village, accommodation buildings, utilities buildings	Follow the general rules for place names; i.e. initial cap each word of the official name for a specific location (e.g. Construction Village); don’t cap generic terms (generic: crib rooms; specific: Crib Room 3)
Other	Phase 2, Operations Phase	Again, the rules re specific (capped) and generic (not capped) for terms such as ‘Operations Phase’ apply. If you’re referring to the specific phase in a particular process, then you cap it; if you’re referring to the time when operations are underway, you’d typically use lower case

[Links last checked January 2012]

Magazines are edited, right?

Magazines have editors, right? So presumably magazines get edited. After all, you don’t find too many errors in most professionally produced magazines.

If only they applied the same rigor when editing their web copy or email marketing copy…

Recieve?

Perhaps they didn’t edit the email marketing piece at all.