ITauthor

This is the first entry in the new incarnation of this weblog.

I've uploaded my old 2002 Radio weblog Thoughts from a technical author onto this site. The pages had been sitting, undeleted on a Userland server since my try-out of Radio expired in August 2002. Thoughts from a technical author was my first experiment in blogging and, like so many weblogs, it doesn't exactly make riveting reading. But, if I haven't put you off, you can step back in time to 19 July 2002 when I posted my first entry.

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.