Technical Writer

In Disaster Recovery part 1 I talked about how important it is for us as tech writers to back up information we have on the PC at home. Information that we may not even realise is important, particularly if we do most of our work for a company on the company PC. However, we still have contacts, emails and a portfolio that we really couldn’t afford to lose.

In this article I want to talk about another backup you need to consider. This is aimed mainly at tech writers in smaller companies, because in larger companies this is covered as part of the implementation project.

Suppose you have the following scenario:

You’re a lone tech writer in a team. Your information is all over the place and you’re desperate to organise it. You go online and find an open source content management system like Joomla (or even WordPress), or an inexpensive one like KBPublisher that you can convince your boss to buy. You get on well with the IT guys and they help you set up a My SQL database and give you space on a server to run it.

(Tech writing) life has never been better. You have a nice little content management system going. People use it. They even add to it, and recommend it to others.

A small system like this is often better for a small company than a monster like SharePoint.  Don’t get me wrong. I like SharePoint, but it is big, and unweildy, and has an incredibly steep learning curve. Sometimes, it’s like using a b-double road train when a bicycle is a better option.

But …

Maybe you have even discovered that your company has SharePoint and have convinced your IT people to implement Windows SharePoint Services for you and are using this for your documentation. 

Either way, what you have is a database system that has fallen outside of the usual IT control. They have let you implement it, and you’re managing it. This means you are responsible for disaster recovery too.

If you have implemented a system like this, ask yourself, “Can I afford to lose this information?” and “What will happen if I do lose it?”

If you answered ’No’ to the first question, and anything other than ’I/we have a disaster recovery plan and we can restore almost everything from the latest backup’ then it’s time to do something about it. 

Most larger system projects provide for regular backups as part of the implementation process, but when a project sneaks in the back way, with a single person implementing it, backups are usually the last thing one thinks about. The implementation is experimental anyway and it’s only when the whole project turns out to be a success that it becomes a real problem.

If you have implemented a content management system like this:

• Do you even know where the data is?
• Do you know if it is backed up at all?
• If it’s not, what are you going to do about it?

You always have to expect the worst, even if it never happens. Data is only as good as your last backup. If your database becomes corrupted, you lose everything.

 For years now disaster recovery has been a hot issue in larger companies.  Smaller companies don’t take as much notice, and little one or two people contracting companies often take no notice of it at all. Yet for writers, whose future work depends on what we can show prospective clients, disaster recovery is a must.

Some of us work from home either full-time or part-time. Many of us have work samples and partly completed work (and even partly completed novels as well) on our PC at home. 

What would happen if your hard disk crashed, or someone stole your PC? How much would it set you back?

I am not talking about a simple lack of a computer here. You can walk into any computer store, buy a new one, and be up and running within minutes—or at worst in a couple of hours if you have to install special software.

I’m talking about work in progress, your portfolio, your notes, your contact information and your emails.

Many people only realise how valuable this is when they lose it.

Writing is a business, and we have to treat it like a business. This means keeping our business information protected, and ensuring that we have a back-up plan for when disaster strikes. 

Most of us insure our homes and our health; many of us also insure against loss of income. Yet there’s one really important thing that many of us don’t consider. Ensuring your data is safe. This one doesn’t even cost as much as the other insurances, all it takes it some time, a blank CD/DVD/flash drive, and a regular back-up habit.

What sort of things should you back up?

• Any work emails on your home PC
• All work, particularly work in progress
• Your portfolio of work
• Contact information
• Invoicing and billing detail

at the very least.

Where should you back it up to?

• Copy it onto a CD or DVD or flash drive and store it away from the PC.

When should you do it?

• Do it regularly.  I do mine once a month, but it really depends on how much you can afford to lose. I should do it once a week, but the monthly one is an easier habit to build because I do it after the bills.

Automate the process as much as you can. In an ideal world your whole backup process would run automatically, and all you would have to do is put a disk into the drive to write the data.  That’s my ideal, but I haven’t got around to it yet.

If you don’t yet back up your home PC, you should at least consider the consequences of losing the data. The worst time to discover you need that data is just after your PC has died.

In part 2, I look at another area of back-ups where tech writers often run into problems.

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.