My regular newsletter from Cherryleaf pointed me in the direction of a helpful article by Pat Holt, a former book review editor and critic for the San Francisco Chronicle. In Ten Mistakes Writers Don't See (but can easily fix when they do), she alerts us to habitual errors that are all too easy to slip into.

Ms Holt is talking about creative writing, but most of the points she makes apply just as well to technical writing.

Number 1 on her list is Repeats. As a technical author I am very aware of repeating myself time and time and time again. So often there's just no way around it, but I really should try harder to stop using "crutch" words. My favourite of these is "typically", which I use all the time because I'm describing software that is extremely configurable. Almost every part of the system can be configured to look and behave differently, according to customers' requirements. So I never know how something will look or respond and I end up starting sentences, "Typically, ...".

Number 3 on the list is another good one: Empty Adverbs. Actually, I'm really not terribly prone to this problem. However, all technical authors should recite Pat Holt's mantra: "Precise and spare; precise and spare; precise and spare." For online help in particular, this surely describes the style we should always be trying to achieve.

Most technical authors should probably have number 9 (Awkward Phrasing) tatooed on the back of their hands:
Awkward phrasing makes the reader stop in the midst of reading and ponder the meaning of a word or phrase. This you never want as an author. A rule of thumb - always give your work a little percolatin' time before you come back to it. Never write right up to deadline. Return to it with fresh eyes. You'll spot those overworked tangles of prose and know exactly how to fix them.

Pat Holt's site (www.holtuncensored.com) is worth a visit. For one thing it's very nicely designed by www.hyperarts.com.

Following on from my last entry, here's another glossary (okay, so it calls itself a dictionary) that's very nicely designed:

www.hyperdictionary.com/computer

I created an in-house glossary here at Memex a couple of years ago, to make it easier for new-starts (like myself at the time) to get to grips with all the acronyms and product names that get bandied about in conversations. I remember coming across the following glossary about then and thinking that its design was much better than my own (except that mine allows you to add new terms or click a term and edit a definition). It's Mike Buckler's Technical Writing Glossary:

http://members.iinet.net.au/~mbuckler/glossary1.shtml

Mike is a technical writer, based in Mt Hawthorn, Western Australia, which is here (his map):

I must get round to improving the look of my in-house glossary. Stumbling upon Mike's glossary again I'm reminded how much better-looking it is than mine.

Christmas and New Year have come and gone and I haven't posted an entry for a long while. Initially this was because I was on holiday. More recently I've been spending most of my available time trying to finish off a technical manual I've been spending way too long writing. The end is now in sight, so I may be able to think of other things again soon.

I spent some time yesterday trying to get to grips with some Javascript to make expand/collapse sections work in Mozilla, Opera and IE. I started with code based heavily on the way Microsoft do it in some of their HTML Help pages (e.g. there's a page about Accessibility in the online help for IE that uses expandable sections). The trouble is their way is a purely IE way and doesn't work in Mozilla. It uses IE-only Javascript properties like innerHTML and sourceindex – both of which are really useful, but I couldn't find Mozilla equivalents, so I had to start from scratch and write my own Javascript file. I'll post this up here sometime so that you can see how it works. What I came up with in the end works quite nicely and keeps the HTML very simple by doing all the formatting in a separate CSS file and using the Javascript to switch the class names of various elements onload, onmouseover and onclick. The images used for the expander links (+ and - icons) and the display properties ("block" or "none") of the expandable block are all defined in the CSS file. OK, it doesn't mean much until you see it!

I notice this week that Framemaker 7.1 has now been released. I have been given verbal approval to buy a copy at work, but I haven't yet managed to get a UK price for an upgrade copy. However, I'm not holding out too much hope that 7.1 will solve all the round-tripping problems I had with 7.0. But I'll keep you posted.

Switching to Thunderbird has, on the whole, been a good thing. However, one of the problems with IMAP is that, because your mail sits on the server, even once you've read it, you need to be able to access the server to see your mail. This morning I'm working from home (as I do most Tuesdays and Wednesdays at the moment) and I've been having problems getting through to my work network. I've just succeeded, on the third attempt. I don't usually have much of a problem. Occasionally it's very slow, depending on what people at work are doing on the network. But the logging on problem is caused by the dynamic IP address my ISP assigns me. The gateway machine for my work network only lets me in if I'm using addresses in a certain range. Usually my address is in that range, but this morning it obviously wasn't the first couple of times I dialled my Internet connection.

I'd like to go broadband, but at the moment I've got a free single-line ISDN connection, and I can't justify shelling out for what would be mainly an aesthetic improvement in my Internet experience.

But I must remember to copy my mail locally in Thunderbird, so that I can read it offline. There was a mail I got from someone at work that had an interesting article about why developers should use design specs, and I wanted to post it here. That'll have to wait. I need to do some work.