Category: Work

As we roll into the holiday season, I’m going to be pausing this blog until the New Year. I’ve found it tricky at times to get into a regular posting schedule here, so that’s something I’m hoping to rectify in 2010.

Looking back it’s been a good year for me, and I’m hoping to take a lot of things forward in the coming year. All of that will be covered here, of course, and I’ve got some plans to revisit some of the topics that I’ve shared with you this year.

Rather than write up a review I thought I’d just see what Wordle thought of my website, which is interesting in and of itself:

Thanks to everyone who has commented or emailed me direct. It has really helped me and I hope it’s helped some of you.

All the very best for the coming holiday season, and here’s to a wonderful 2010!

A few days ago I received an email about a new website. I’ve seen it mentioned on other blogs but think it’s worth repeating as there is some useful information there.

I am contacting you because I have just thought that maybe a post about my new web site on software documentation and user assistance could also be interesting for your readers. In addition to about 250 useful links for technical writers, the site for example provides checklists and up-to-date market surveys of more than 350 help authoring tools, screen capture tools, screencasting tools and other utilities for technical communicators. All information can also be downloaded as a PDF booklet (approx. 100 pages).

On the website you can find some basic know-how, checklists, tools and links, which will help you to create clear and concise user-friendly manuals, online help files, software demos, tutorials and other forms of user assistance. Go have a look.

Thanks to Marc Achtelig of indoition for getting in touch.

What a wonderful group of people you are, my dear readers and fellow Twitterers. I asked for some suggestions as I’m pulling together a short, internal, workshop covering some simple techniques and tips for the “non-writers” in our organisation.

I received some great suggestions and a couple of excellent links and, as promised, here is a generic version of the presentation.

The one I’ll run internally has some examples that are specific to the audience and our organisation, so I’d suggest if you are going to use the presentation I’ve provided, that you add in your own examples. Much easier for people to understand if they see real examples in action.

How do you get started? Faced with that pristine new document, all that whitespace, what do you generally do to start writing that document?

Like most companies, we have a number of people who create content in a number of different styles and formats. The main producers are, of course, the technical writing team, but after that there is still a fair number of documents which fall into the “creative writing” bag including whitepapers, proposals, product sheets and so on.

The people involved in writing these documents are, for the most part, promoted internally and have had no formal training in how to write. I was chatting with one of them recently and he said that the biggest issue he had was just getting started, and once started he couldn’t really tell if what he was writing was particularly well structured.

“Hey” he said, “could you train us to be writers?”

One day I’ll learn not to say YES to such questions, but it seemed a reasonable request at the time.

The thing is, I’ve never been trained as a writer either, and writing technical documentation follows patterns which other types of document don’t necessarily follow. On the other hand, any pattern is better than no pattern and if I could introduce some basic methodologies, surely it’s better for everyone?

Luckily for me I had still had fresh memories of attending a particular session at the Technical Communication conference. Kim Schrantz-Berquist presented If you can write an article, you can write anything! in which she covered a couple of writing techniques which I think will be perfect to introduce to the ‘creative writers’ in our company.

The first one I’ve adapted quite a bit to better fit with the intended audience, but the principles of the 5Ws and 1H remain the same. If you cover Who, What, Why, When, Where and How you won’t missing anything, and it’s a good way to kick start the brain, and get past that first blank page.

Kim also covered the Inverted Pyramid, something more typically used in journalism, that loads all the important information at the top of the article, ideal for business writing as it allows people to ‘get out’ of the document without missing out on crucial information.

I’ve taken the techniques she covered, crafted some examples specific to our organisation, and a little bit about Active vs Passive, a few slides on grammar that build on advice from Prof. Pullum (basically, don’t sweat it and write as you would speak) and will hopefully deliver the first workshop next week.

But before I do that, I’d love to hear if you have any other techniques that could help.

Having been in a bit of a lull, I recently asked those who follow me on Twitter what I should blog about. This post is in response to a suggestion from Peter Anghelides who replied: “Blog about why you became a technical author?”

Which is a good a topic as any as, like many people in this industry, I certainly didn’t set out to be a Technical Writer, far from it.

For me Technical Writing combines two of my early interests, words and technology. Growing up I read a lot, and was lucky enough that my Dad used to bring a computer home at the weekend. BBC (Acorn) Micro, and later the first Mac Plus. I’ll happily admit to crafting documents (leaflets and the like) in every single available font on one page!

When it came time to leave school, Physics was my main interest area, and looking to add a technology slant I chose a course in Electronic and Electrical Engineering. In hindsight that was a mistake but it’s not something I regret. A few years later, with University behind me, I had converted my part-time job in McDonalds to a full-time job as I cast about for a ‘real’ job!

It was my Mum who spotted an advert in the local paper from a company looking to hire a “Technical Administrator”. The role was a mixed bag of tasks, largely supporting the small development team (all 12 of them) and after successfully negotiating a short writing test about how to use a flatbed scanner, I was soon put to work, writing documentation for their application. With little or no instruction or guidance I looked to those big clunky manuals that I had sitting on my desk, and it’s no small coincidence that the documentation I produced bore a striking similarity in style and layout to that of the Adobe FrameMaker 4.5 manual.

Towards the end of my time there, in 1995 if I recall correctly, I was sent on a two-day training course on how to create HTML pages with a view of setting up a company website. And so my journey on the internet began.

Having been made redundant I moved to England to Dr.Solomons where I gained a LOT of knowledge in a short space of time, working in a well organised, well run team. Some of the lessons learned there I now find myself echoing to my current team. A brief stint running the team also made me realise that I was capable of taking that step up.

The next role relied on my web expertise (a large part of my time at Dr.Solomons was focussed around web delivery of information) and also took me into another large company (was Tetra, now owned by Sage). A different working environment, and yet more to learn.

It was during those early years of my career that I realised that I’d fallen into a wonderful world where I could, if I so wished, dip my finger into a manner of different discussions and be involved with a large variety of people in different areas of a company. I’d speak with the QA engineers about issues with the product, talk to the Product Marketing team about how the product was being sold and who was buying it, the translation team were at the next set of desks and I’ve been lucky that most of the developers I’ve worked with have all been smart, friendly and helpful individuals. Even the grumpy ones.

My first step into team management was taken with some trepididation, but I’ve always trusted my own ability to learn quickly and with a little guidance (and one awful mistake) I think I’ve a good handle on how to get the best from a team of technical writers (for the most part, let them get on with it, they are more than capable without me!) and in the past couple of years I’ve learned a lot about selling our role to the company.

I’ve been lucky, both in the decisions made about my career (not all of which I’ve had a say in with two job changes brought about through redundancy) and especially in terms of the people I’ve worked with. I’ve learned so much from my colleagues, mentors and managers that I do sometimes wonder quite how I got where I am today.

And that’s why I’m happy to say that I’m a Technical Writer*, that I work in the field of Technical Communications and I don’t see either of those things changing any time soon.

* not that I do a lot of writing these days, my official title is Technical Information Manager, read into that what you will

Better documentation lowers support calls, is a widely held assumption and one I’m hoping to prove in the coming months. With our new knowledge centre in place, and Google Analytics tracking how many people are visiting it, I’ll soon have stats for my side of the fence.

Early numbers (from the past two weeks) show that more people are looking at the Documentation area of our website than are looking at the Support area, but then the knowledge centre (part of the Documentation area) is new so that’s only to be expected and I’m really not expecting to get a true picture of how things are going until late January next year.

Fingers crossed.

With thanks to Rachel Potts for her post on what web analytics can do for technical communications.