Technical Writer

• 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.

An anti-Microsoft rant.  Unusual, because I like their products and 90% of all the computer programs I use are Microsoft.

Here in Australia—and I believe the rest of the world—Apple are running a series of Mac vs PC ads.  Most of us have seen them by now.  One in particular really resonates, the one that has a go at the overly intrusive security system on Vista, which requires users to cancel or allow virtually all user actions in an effort to make the PC secure.

We have Vista at home on one PC, and sometimes I want to turn off all security because those annoying messages frustrate me.

The worst thing is, I’m not even sure where the problems really are.  Vista, or Internet Explorer 7 (IE7).  I suspect it’s a combination of both, but that makes any problem twice as difficult to track down.

IE 7 was released not long before Vista. I know I started using IE7 only a month before I got Vista.

Here are three specific examples I have personally come across, one work related, two from home.

• At work, on our SharePoint Portal Server (2003) we use Microsoft Office web components.  We have used them for over twelve months with no problems.  Users have no problems accessing them, provided they set their portal server as a trusted site.  Recently, a small number of users upgraded to IE7, and suddenly we’re having problems with web components.  If the site is not a trusted site the user gets a message warning them that someone is trying to download date, asking them to okay it.  If the site is a trusted site they simply get an error. I am sure it’s only a setting, but it is extremely frustrating.  You would think that Microsoft would have ensured their own products were compatible, at the least.
• Vista and Java.  The home PC that runs Vista blocks Java on startup.  I have to go in and physically say it can run every time.  I can see no logical reason for this except that Java is a non-Microsoft product. Few people go long on the internet nowadays without running a Java applet or two.  Microsoft knows this, so why bother to make it so hard?
• The Microsoft genuine advantage. By the time you put up with having to manually load Java, and issues with programs that used to run perfectly but no longer do, you start to get annoyed with everything the company does that isn’t seamless.  This last issue probably isn’t really an issue, but compounded with the other two problems, it is really annoying me.My software is the genuine article.  Every Microsoft product is either store bought, with genuine serial numbers, or in the last two months it’s part of my TechNet subscription. Two days ago I attempted to download the Microsoft Save as PDF addin.  This is one of those products that Microsoft validates first, to ensure that you have a genuine version of Office before it will allow you to download the addin. That’s fine. I do have a genuine version of Office.The validation failed and it took two days to find out what was wrong.It turned out I had an unregistered copy of Visio on my PC.  I had loaded Visio up one day last week, but had not yet got around to entering the registration code.  You know how it goes—sometimes you get called away in the middle of things, and come back to it later.  It’s not even part of the standard Office suite.

The whole security thing is really annoying me at present. 

I am reminded of a security expert I worked with, who once recommended that I never create forms where the user had to okay alert that told them when something was happening, when those things were not errors.

“If you make them click okay all the time when nothing is wrong,” he said.  “They start ignoring the messages.  Then, if something really does go wrong, they miss it, because they’re so used to ignoring the messages.”

That’s about where I am at with Microsoft at present.  I am sick of their so-called security, which is continually bringing unimportant matters to my attention.  I am already at the stage where I ignore any messages Microsoft puts up, and all I want to do is turn the whole security thing off.

I’m having more fun with my TechNet subscription than I expected to.

It’s a 12-month subscription to pretty much every program Microsoft.  I purchased it because our work has decided not to upgrade to SharePoint 2007, nor to Office 2007, and I need to keep up-to-date with the technology. I am planning on moving on some time (hopefully this year).

I haven’t got around to installing SharePoint yet.  So far I have only installed the standard Office programs but it has been good to learn about each of the new versions. 

I know I could have run the trial version versions, but these are full versions and I don’t have to worry about time limits.  I can also test out various programs that I wouldn’t otherwise touch, like Groove.  (I still haven’t figured out where Groove fits in.  I mean, isn’t it doing similar things to SharePoint, only off-line?)

It’s not cheap, but it’s value for money if you intend to use the full suite.

I was speaking with another technical writer the other day, and the subject turned to tools of the trade. It’s always interesting to know what other people work with.  The software we can’t do without.  Here’s my list.

Microsoft Word

No matter what you say about Word, it’s a powerful tool, particularly when you start using functionality like styles, templates and macros.

This is probably the most basic tool in the tech writer’s toolbox.

SnagIt

You have got to have a screen capture program.  I use Tech Smith’s Snag It, and was so impressed with it at work I bought it for my home PC.

It has since become my graphics tool of choice as well. When I need to simply crop or resize a graphic I open it in Snag It rather than, say, PaintShop Pro.

XML Spy 

I seem to have been using Altova’s XML Spy for years now.  Each release gets more complex, with more features, but it’s the simple features that have been with the program for a number of releases now are the ones I can’t do without.

• Pretty print
• Schema diagrams
• Generating schemas
• Grid views (and the ability to switch between grid and text view)
• Quick transforms
• Creating updating XML in the grid

and the functionality they have really improved in the last couple of releases:

• Generating XML from databases.

As an XML editor, I think it’s still one of the best.

Captivate

I first came across Captivate at a conference. It had just been released, and Macromeida had someone there to demonstrate it.  The salesman loved the product, and it showed.  It was an impressive demonstration and and impressive product.

At the time Macromedia had just bought out RoboHelp, and everyone was asking “Was RoboHelp dead?”.  It looked as if it was, but MacroMedia seemed more than happy with RoboHelp’s little brother—RoboDemo—which they turned into Captivate. 

(We all know how that story ends, of course.  Adobe bought Macromedia, and suddenly the pre-eminent on-line help system had a new lease of life, along with it’s little brother. They’re both going strong.)

Captivate is a great tool for creating on-line training.  Check it out.

Dreamweaver

An oldie, but a goodie.  Everything you need in the one package to create web pages.  I am still using version 4, while Adobe is up to version 8, but I still couldn’t live without it (work-wise, I mean).

So there you have it.  Those are my tools.  Despite what I say, I probably could live without them all.  All one really needs is Notepad, after all, or some other text editor, but how much work would we get done?

I used Dreamweaver this morning to add 100 links to a site.  It took less than an hour.  If I’d had to do it in Notepad I would have been at it all morning.

The Dummies series of books are a writer’s dream.  Clean, well written, with personality and an easy read.  Perfect as both a reference and as a learning tool.

I flicked through Digital Photography for Dummies over the weekend.  Very nice.  My business partner, Calder, also recommends QuickBooks for Dummies. Yet the only Dummies book I ever read was C++ for Dummies, and I confess I didn’t read much.

My C++ was rusty.  I had spent two years coding C++ at university but hadn’t touched it since, and then I had to document code written in that language.  I bought C++ for Dummies as a memory jog.

I never finished the book.  I couldn’t understand it.

The author constantly referred back to how things worked in C, which I had never used. It totally lost me as a reader and I didn’t bother to read more than a couple of chapters. I will never know how good the book was, or wasn’t.

Comparing new programs to old ones works for a cutover period, when the bulk of people using the new program are converts from the old, but it becomes really frustrating after that, even to these converted users.

Microsoft has just released (or is about to release) Office 2007, and I imagine this will bring on a rush of cross-over books, which is fine, but for how long are they needed, and what do you do with them after they are finished?

A lot of cross-over information will be posted on the word wide web and on intranets.  A lot of it will stay there long after its use-by date.  They gradually disappear, but even now the occasional Google search brings up instructions on how to do something in Office 2003 compared to doing the same thing in Office 95.

A lot of the cross-over material gets forgotten.  I recently looked at some old “Introduction to SharePoint” CBTs I wrote for our implementation of SharePoint as an intranet, and realised that some of these modules still referred to ‘how we will do things in our new system’, even though we have been doing it this way for two years now, and over 50% of our current staff had not even been working at the company when we implemented it.

When do you know it’s time for the cross-over material to go and how do you keep track of what has to be changed?

Maybe there’s another way to do it.

Microsoft have introduced the interactive: Word 2003 to Word 2007 Command Reference Guide which allows you to choose a menu option in Word 2003 and then shows you how to do the same thing in 2007.

I really like this, because I am not good at remembering the names of commands. 

If I want to change a style I know which menu I have to go to, and which option to click on when I get to that menu, but if you asked me how do do it I wouldn’t be able to say, “Click on the Format menu, and then choose Styles and Formatting.”  I would have to check it and do it.

Using a tool like the Word 2003 to Word 2007 Command Reference Guide I can re-write procedures totally in Word 2007, but for those people who already know what to do in Word 2003, I can just provide a link and say, “Go to it.”

Later on, when everyone is familiar with Office 2007, I can remove the link.

It’s much tidier, and a lot easier to manage.

First of all, understand that you don’t have to learn it.

Every year more and more toolds come out that help place a layer between you and the native XML.  In a few years time you will hardly even realise there is XML underneath.

Likewise, Microsoft Office isn’t going to disappear in the near future.

RoboHelp I’m not so sure about. When Macromedia bought them out the product was pretty much declared dead. Then Adobe bought Macromedia and seemed to have different ideas. Not being a regular user, I haven’t kept up with what’s happening.

No matter which tool you use, it’s dangerous to base your career around entrenched technology.

My first technical writing jobs used desktop publishing tools—Ventura Publisher and FrameMaker.  Where would I be now if they were the only tools I ever used? Most likely looking for work, unable to pick my jobs, desparate for anything that came my way that suited my skills. (I saw an advertisement last week for a technical writer with FrameMaker skills, the first such job I had seen in a long time.)

So keeping up to date ensures you still have a job.

There’s one other major advantage.

Money.

When skills are in short supply, the rate goes up. It’s a simple matter of supply and demand. Learning and knowing up about tools such as DITA and DocBook before most other people know about them mean that you are likely to get better paying jobs. Not to mention that companies that are early adopters of technology are often good places to work.

It’s worth the effort.