Technical Writer

I’m back from the AODC. Exhausted, but stimulated.  Here’s a smattering of thoughts, notes and other things, in no particular order.

• There are a lot of lone tech writers out there. Conferences like this are fantastic, because you realise that other people have the same problems as you do—access to SMEs, other people in the company not understanding what you do, always being put off until the last minute on projects
• It’s the best place to network. Even if you’re an introvert it doesn’t matter. (Many of us are.) You sit at communal tables at lunch time, and you stand around in groups at breaks. All you have to do is listen to other people talk if you haven’t the courage to join in. By the end of the last day you will have talked to a few people, believe me
• Talk to other attendees about your problems with tools, projects, experiences. They may be able to help; and they, of all people, will understand what you are going through
• If you’re a newbie, and you have only ever used, say, Word, for your tech writing, don’t worry, and don’t be put off by the fact that everyone’s talking about DITA, and XML/XSLT and embedded user assistance. It overwhelms you at first but by the end of three days you’re starting to get a feel for a much bigger tech writing field out there than just Word, and you’re in the right place to learn about it.

Tools and buzz words

• XML is still the way of the future
• Ditto CSS
• We’re all trying to go modular, when we can
• XML schemas are important. DITA and DocBook are the two mentioned, with most of it being about DITA
• Classic .CHM files help is still around but web-based help is, and has been for a number of years now, but really web-based help and embedded user assistance is the way to go
• Video capture programs like Captivate and Camtasia seem to now be a part of the tech writer’s toolbox
• RoboHelp and Flare got mentioned a lot
• Web 2.0

Final comments

• Half the attendees were male. I could be wrong, but I think that when I started going to these conferences it was roughly 80/20 women to men
• May is a really nice time to visit the Gold Coast.  The weather was perfect. Not too hot, not too cold, and the beaches were glorious (and the food wasn’t bad either)
• Tech writers are a great bunch of people.

I’m off to the Australasian Online Documentation Conference (AODC), which is always good value.

This year it’s in sunny Queensland—Surfers Paradise, in fact—so I’m looking forward to three days in the sun, learning new things and meeting lots of other technical writers.

• Of all the sites I would love to have developed, the W3Schools site has to be top of my list.

It’s a site for developers, and it teaches you how to build web sites. As a training tool it succeeds on every level a user required. It was created by Hege, Stale and Jan Egil Refsnes. They have done a fantastic job.

Let’s talk first about what it doesn’t have.

• It doesn’t have fancy training videos
• It doesn’t have Flash (except in the Flash tutorial)
• It doesn’t have voiceovers

In fact, at first glance, it looks very much like a site that might have been written in the early days of web design (well designed, but still almost static html). Where are all the bells and whistles that people are used to now?

They don’t need them.

What the site does have, to paraphrase some of their readers, is:

• Easy explanations
• Excellent reference guide
• Try it yourself on-line examples
• Free

Quoting Chris, from About Comments from Visitors on the W3Schools web site.

And also Donoho:

Every link I click takes me to more information I didn’t even know I wanted.

• The layout - makes navigation a non-thought.
• The content - simply expansive.
• The examples - EXACTLY what I need and nothing more.

I dream of building sites that are as easy to use, informative, helpful and productive as this one.

So why is the site so good? What makes it work, and what makes 11 million visitors drop in over a one month period?

Obviously, the writing has a lot to do with it.  The Refsnes can obviously write well. Not only that, they take what most people see as complex technical information and break it down into easily digestible chunks. Even if you don’t think you are technical, try out their Introduction to HTML and see if you can work it out.

But it’s not just the writing. There’s more. There’s the way everything is laid out so you don’t have to look hard to find something. There’s the way the information is chunked so that you don’t have to spend five or ten minutes reading through a tutorial when all you want is, say, a quick refresher on how to use the xslt choose element. There’s the way you don’t get bogged down in extraneous detail, all you get are the basics.  And, of course, there are the examples.

I have to say the Try-It examples on W3Schools is some of the best use of web technology I have seen. And the weird thing is, it’s (relatively) basic technology, deceptivly simple and it’s great.

It also suits its audience. The audience is web developers, and it has the full range of experience covered. Beginners can do the tutorials, experienced users can drop in and look up a quick reference on something they haven’t used in a while.

It’s comprehensive. It provides and introduction to pretty much everything you need to know about web development.

It works.

As another user commented:

I point to your site as an example of how to teach on-line. 

And so do I.