Archive for July, 2009

h1

Two different approaches to words

July 31, 2009

Save the Words

A clever promotion by the Oxford Dictionaries people, the Save the Words website (http://www.savethewords.org) alerts you to old, unused words, and lets you adopt them and encourages you to use them in everyday speech so they don’t disappear. In their own words:

Save The WordsYou can also click on the little word boxes in the background to get a definition for that word.

Wordnik

Wordnik (http://www.wordnik.com/) is not a traditional dictionary:

Traditional dictionaries make you wait until they’ve found what they consider to be “enough” information about a word before they will show it to you. Wordnik knows you don’t want to wait—if you’re interested in a word, we’re interested too!

Our goal is to show you as much information as possible, just as fast as we can find it, for every word in English, and to give you a place where you can make your own opinions about words known.

By “information,” we don’t just mean traditional definitions (although we have plenty of those)…

I did a search on Wordnik for ‘berm’, a term I’d come across while editing documents for the oil and gas industry. I got definitions from several dictionaries, a history of the word used in context, statistics of its usage, and some Flickr photos of a ‘berm’:

wordnik

(Thanks to Fran D for alerting me to Save The Words, and to Stuart B for alerting me to Wordnik)

Update: And for a THIRD approach to words, check out Wolfram|Alpha’s word search capabilities: http://blog.wolframalpha.com/2009/07/29/wolframalphas-got-the-write-stuff/

[Links last checked July 2009]

h1

This is why you need an editor

July 30, 2009

Spell checkers are great, but they aren’t a substitute for a real editor of the human variety. A human editor understands context, and would know that this word — while spelled correctly — is not the right word!

It's all about context

It’s all about context

h1

This is new… or I’m blind

July 29, 2009

Whenever I have to travel somewhere within Australia or overseas I check hotel prices on wotif.com before checking direct with the hotel websites or calling the hotels (it’s amazing how many will match Woitf’s prices when you call them!). Sometimes Wotif is cheaper; sometimes going direct is cheaper — for the same room.

Anyhow, Wotif also has a good summary of the features of various room types and the hotel in general. I’ve been using Wotif for several years so I’m pretty familiar with the website’s layout and how to use it. So I was surprised when I noticed a new category in the list of hotel features —  either I’m blind or they’ve only recently introduced ‘Gay friendly’ as a feature of a hotel.

hotel_gay_friendlyI’m not sure what it means — perhaps the hotel clerks don’t raise an eyebrow when two people of the same gender check in together; maybe you get put on a separate floor like people with pets in a ‘pet friendly’ establishment; or you get a special area (rooms/floors) like smokers; or maybe you get special doors and showers just like if you are in a wheelchair; perhaps it means that like smokers and people in wheelchairs, you have  to declare your sexual orientation when booking a room!!

So, what would happen if you are a gay smoker, in a wheelchair, and travelling with a pet? The mind boggles…

Actually, the more I think about this, the less I like it. Initially, I thought that such a categorisation might be good for people who were gay — they knew they could go to such a hotel and not be given ‘the look’ by the hotel staff. And perhaps that’s ALL it is.

But the more I think about it, the more I think it’s not right. People are people. When you check into a hotel, it should be none of the hotel’s business if you are a heterosexual couple, brother and sister, two sisters, two brothers, husband and wife, mother and daughter, father and son, uncle and nephew, two friends or business partners… you get the picture. So is stating that they are ‘gay friendly’ another form of discrimination by these hotels? I know that when I do an internet or phone booking, or even turn up at the reservation desk, no-one asks my sexual orientation and no-one even cares if there’s someone sharing the room with me. The most I have to do is state how many adults and children in the room. I wonder if the day will come when we have to put our sexual orientation into a ‘special needs’ section of a hotel reservation web form! Yes, I know that’s perhaps taking this a little too far, but there are already places for you to state your smoking preferences, special needs for wheelchair access etc. on these forms.

Your thoughts about this category/feature for hotels?

h1

Editing: Terms and citations in long documents

July 28, 2009

Do you have a long document to edit online? Perhaps an academic thesis, a scientific report, a government document — one with long lists of terms and references, as well as citations throughout the document for those references.

One of the difficulties in checking terms and citations against their respective lists in long documents is the painful process of moving around the document — you’re forever flipping from one end of the document to the other, then trying to get back to where you were up to in the editing process. Yes, there are techniques to minimize this, but they aren’t entirely satisfactory.

One method is to use Word’s ‘highlighter pen’ to mark up all the terms and citations as you’re editing, then come back and check them with another pass (or two) over the document. But this takes quite a bit of time, especially on a large document. And you’re forever grabbing the highlighter tool to add highlighting, then to remove it after you’ve checked the term/citation. (See Add/remove highlighting with the keyboard for a quicker way than the toolbar icon, or https://cybertext.wordpress.com/2019/10/31/word-find-and-highlight-words-of-two-or-more-capitals/ for getting Word to highlight all the acronyms, initialisms, and abbreviations that are capitals.)

If you use the method I describe below, you can speed up the process and do the checks as you edit the document.

NOTE: This method is most effective if you have two or more monitors or one very wide monitor.

Create your supplementary documents

  1. Open the large Word document.
  2. Find the list of terms and copy it.
  3. Paste the list of terms into a new document (e.g. terms.doc).
  4. Highlight all the terms in the terms.doc document and save the document. Do not close it — move it to the other monitor.
  5. Go back to the main document, find the list of references, copy it, then paste it into another new document (e.g. refs.doc). Again, highlight the entire list of references in the refs.doc document, then move this document to the other monitor too.

You should now have three Word documents open — the main (long) document, and two much shorter documents (terms.doc and refs.doc). The two small documents should be fully highlighted.

What you’re going to do as you’re editing is remove the highlighting for any term or citation you find that matches one in the relevant list.

Check off the found terms and citations

  1. Start editing the document as you normally would.
  2. As you come to a term (abbreviation, acronym etc.) in the main document, check if it’s in the terms.doc list.
  3. If it is, remove the highlight from that term. At this stage you ARE NOT checking the correctness of the definition — just whether the term is listed in the terms list or not. (See below for tips to deal with terms that aren’t in the list.)

    Remove highlight from found terms

    Remove highlight from found terms

  4. Do the same for any citations you come across — check that the item is in the refs.doc and remove the highlight if it is.

    Remove highlight from found terms

    Remove highlight from found references

  5. By the end of editing the main document, you should have few, if any, highlighted terms or references left in their respective documents.
  6. If you have no highlights, you’re now ready to check the two smaller documents for their accuracy (i.e. check all definitions are correct, check all references are formatted according to house style, etc.)
  7. Once you’ve completed step 6, copy and paste the two lists back into the main document, overwriting the existing lists. And you’re done!

Things that can go awry

  • Term in main document is not in the terms list:  Add it to terms.doc and perhaps highlight it in another color if you think you won’t pick it up later (unlikely as you will go through the terms list verifying the definitions later anyway). You may need to add the definition (if you have it), or alert the author that the definition is missing.
  • Citation in main document is not in reference list: Alert author to it; it’s their responsibility to make sure the reference is included, or to delete the citation if it’s no longer applicable.
  • Term is still highlighted in terms.doc:  Do a Find (Ctrl+F) just in case you missed it. If it’s really not there, alert author to it for possible deletion from terms list.
  • Reference is still highlighted in refs.doc:  Do a Find (Ctrl+F) just in case you missed it. If it’s really not there, alert author to it for possible deletion from reference list, or as a reminder that they may have forgotten to add a citation.

[Links last checked October 2009]

h1

What are you worth?

July 27, 2009

Although Pamela Hewitt’s article — titled What are you worth? — is written for editors, many of the points she addresses apply equally to the technical communication profession. If you’re in the editing or technical communication fields, I strongly recommend you read it. Now.

I particularly liked:

If I undercut my colleagues, in the long run I undercut myself. If I sell myself short, I sell my colleagues short. If I don’t value my own services, I undervalue the services of my colleagues. I prefer not to do any of these things. I would rather that my colleagues didn’t behave this way towards me.

Her article is here: http://www.iped-editors.org/content/what-are-you-worth%3F

[Links last checked July 2009]

h1

Writing resources

July 26, 2009

June must be the month for publishing compilations of writing resources and tools!

In June 2008, a list of 100 Useful Web Tools for Writers was posted on the CollegeDegrees.com blog.

And in June 2009, Smashing Magazine had a list of 50 Free Resources That Will Improve Your Writing Skills.

While there is some crossover between the lists (Smashing Magazine even mentions the 100 Useful Web Tools site), the lists are different enough to cater for all types of writers and the various issues that writers might come across.

Here are the subtopics for each:

100 Useful Web Tools (http://www.collegedegrees.com/blog/2008/06/11/100-useful-web-tools-for-writers/):

  • Getting Organized
  • Finding Inspiration
  • Getting Gigs
  • Communicating with Vendors, Editors and Partners
  • Networking and Marketing
  • Just for Writing
  • Staying Grounded
  • Productivity Tools
  • Getting Paid
  • Fun Little Extras
  • Protecting Your Livelihood

Smashing Magazine (http://www.smashingmagazine.com/2009/06/28/50-free-resources-that-will-improve-your-writing-skills/):

  • Grammar, Punctuation & Co.
  • Common Mistakes and Problems
  • General Writing Skills
  • Practical Guides to Better Writing Skills
  • Copywriting Blogs
  • Tools
  • Further Resources

[Links last checked July 2009]

h1

They have to be joking…

July 25, 2009

I saw this job ad via a Google alert for “technical writing” last month:

job_ad3

Even at 20 articles per day at 300 words, that’s some 6000 words per day, written AND edited. And in an area like IT. All for $100.

Command of the English language is obviously not a prerequisite based on the language used by the person who wrote this job ad. And at $5 per article, it’s clear they don’t care about any sort of quality.

They don’t want a technical writer — they want a slave!

h1

I love new terms!

July 24, 2009

I love working in new industries. They each have their own language and jargon, and sometimes, just sometimes, the language they use is really funny. Take the incident report below — the event is not funny, but the terms? Mouse Hole Pipe and Rooster Box? Where do they come from? (By the way, the industry is oil and gas and these things are on the seabed — a long way away from where your standard mouse or rooster lives! They also have ‘slug catchers’…)

A Mouse Hole Pipe and a Rooster Box went walking...

A Mouse Hole Pipe and a Rooster Box went walking...

h1

Happy 10th birthday, CyberText!

July 23, 2009

On July 23, 1999 CyberText Consulting Pty Ltd was registered as a business in Western Australia. That’s 10 years out on my own, being an independent contractor, freelancer, whatever you want to call it. Wow! Who’d have thought?!

A bit of back story

I left teaching in 1992 to work in a library software company. In the 6 years I was there, I segued into writing the software manual (paper!), the training materials, the company newsletter, even some of the promotional materials. I also taught myself how to create WinHelp (the hard way — with RTF files and A and K markers and the WinHelp engine…), taught myself HTML (no CSS in the mid-1990s), and developed a many-hundred page website for that company — all in Notepad. Somewhere in the last months there I discovered Help authoring tools and WYSIWYG HTML editors, all of which could make my life easier. I also discovered that what I’d been doing — without a job title — came under the umbrella of ‘technical writer’. I had tools and a title! But very soon no job as the company imploded upon itself after a takeover 6 months earlier by another company. A long story best told over a bottle of red…

The first weekend in my life without a job was spent hunting the job ads. And I found one for a technical writer with a local software company. I applied and got the job, starting some 4 weeks later. Twelve months later — and after a lot of intensive on-the-job learning on my part — they decided they didn’t have enough work for me (it was the beginning of the dot com bust), and suggested I go out on my own as a contractor, contracting back to them. They also said they would be OK with me going for a tech writing contract at a BIG company I’d been pursuing on their behalf. That was like a gift from heaven — thank you, Nathan H! And they said they’d keep me on until I got my business up and running. They were great people to work with.

Well, the BIG company were happy to take me on for an SAP documentation project, although I had no SAP experience and had never worked with a team of tech writers before. In fact, I didn’t even *know* any other tech writers before that first contract. But I did know how to write, and I did know HTML (well, more than many people did in those days). And I was as scared as it was possible to be. I’d been an employee all my life — starting a business was a very frightening proposition, though some of the pain was taken away by getting a steady 6-month gig at an hourly rate I hadn’t thought possible.

I started CyberText as a result of that forced layoff, and the rest is history! Ten years on and “I’m still lovin’ it, baby!”

And SAP documentation? I did a couple more gigs with it, but I found documenting SAP very tedious and at times mind-numbingly boring — it paid well, but it didn’t light my fire. My heart was with smaller software companies who were doing cutting edge stuff, being a lone writer/jack-of-all-trades, and learning about all sorts of cool stuff.

h1

Add steps, tips etc. to videos

July 22, 2009

There’s a new kid on the block offering a service that lets you upload your instructional videos and add steps, tips, titles, etc. to them, then share them with the world. The product is Howcast, and as far as I can tell, it’s a free service.

The image below shows a video with some Howcast features added:

Screen shot of a Howcast video frame

Screen shot of a Howcast video frame

The dots at the bottom of the video repesent steps (white dots for those to come, black for those already seen; green dots for tips, and red dots for warnings [not shown]). You can hover over a dot to see the text associated with it — in this example, an instructional step (“Step 3 Take pictures outside in the morning of before sunset”).

Howcast’s website also has text instructions in a Wiki format (Wiki Guides) for those who don’t do video.

And for those who can’t afford or justify more complex software, such as Adobe’s Captivate, Techsmith’s Camtasia and the like, Howcast might be a viable option for the occasional instructional video you need to produce.

Howcast website: http://www.howcast.com

[Links last checked July 2009]