Technical Writer

I’m feeling depressed today. It’s a combination of a lot of little things:

• A new boss, who doesn’t understand what it is that technical writers do, let alone what I’m doing in his team
• I need to document a system process by tomorrow night but I can’t get access to that particular system
• A workmate comes to me as a last resort. They had tried to purchase a new system to store specific data but couldn’t get budget for it. They wonder if I have any suggestions for an alternative. I tell them a single SharePoint list will do the job for them.

That’s right. One single SharePoint list. Yet they were prepared to spend hundreds, maybe thousands, of dollars to buy a new product just to produce the same information as a single SharePoint list with a number of different views.

We discussed how many lists my workmate really needed. She thought ten, one for each of our major customers.

I try to tell her that, no, if she adds an extra (checkbox choice) column for the customer name then she only needs one list, especially since 90% of the information is exactly the same for each customer. But no, she wants to duplicate the information ten times over. I set up a sample for her but she goes away not convinced.

I have no authority. I am only the technical writer. Had I been, say, a business analyst or system architect, or even a developer, then obviously I would have known what I was talking about and she would have seriously looked at the proposition.

It’s the same with the access problem. It’s a remote system. I can’t get into it. Our Service Desk guys can’t get into it. So, we (Service Desk and I) have logged a request with the people who manage the remote site. I know that request will drop right to the bottom of the pile. Because I am only a technical writer and therefore unimportant in the scheme of things.

[I have no complaints with our Service Desk, by the way. These people are fantastic. Patient, good-natured—which is pretty hard given some of the work that is heaped on them, always ready to help—despite how stupid a question may be. They keep systems running smoothly 99.9% of the time, and yet the only time they really get noticed is when something goes majorly wrong. Then it’s usually bad notice.]

But it’s the new boss that really depressed me. Here we go again. I now have to sell myself and my product—me, and my technical writing—all over again.

Sometimes I wonder if it is worth it.

The problem with being a sole technical writer in a team or a company is that no-one really knows who you are or what you do, and you have to convince them of your value. It’s even more of a problem if your team leader or manager doesn’t accept that you really are a part of the team. You become demoralised, your work gets worse, which affects your morale even more, and your ability to fit into the team, which affects your work and so on in an ever increasing downward spiral.

I think that most of us who are sole technical writers have experienced this problem.

At a recent conference I attended, one of the presenters spoke about this alienation, about no-one understanding your value to the company or your team. A goodly number of us in the audience nodded.

“You know,” he said, “That it’s your fault. It’s up to you to convince people of your value, it’s not up to others to do it for you.”

I agree with him.

Just being able to write doesn’t automatically make you a good technical writer. Two other skills that are more important are project management and people skills. People skills do not just mean being able to coax the developer into giving you time out of his/her busy schedule, it also means networking and selling yourself. Yet a lot of technical writers are far stronger in the technical and writing side than they are on the people side.

I am one of these.

Marketing is hard work, and right now in my depressed state I wonder if it’s worth it.

I will feel better tomorrow. Most jobs have components you’d rather not do, and there aren’t many better jobs than tech writing, so tomorrow I will see how I can convince my boss I add value.

But for tonight, I think I’d like to wallow in self-pity.

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.

I have been a technical writer for a long time now. When I started there were no technical writing qualifications. The only requirement was that you had a degree of some sort, and even that wasn’t really compulsory. I know some technical writers who came up through clerical roles. Others, like me, are former programmers. A lot of them are trainers who decided that they could write better training manuals than the ones that were forced on them. Some people, like me again, deliberately choose to become technical writers, while a large percentage seem to fall into the role.

And as for courses on technical writing, there was nothing.

One of our local universities now offers a post-graduate certificate/diploma in technical communicaton.

I am glad they made it a post-graduate course though, because one of the things that really helps a technical writer when they are starting out is experience. The experience of user who knows the business processes behind a system they have used day in and day out, the experience of a trainer who knows what it is like to get up in front of a group of adults and use materials that someone else has written, even the experience of a developer who has written code for a system and can understand some of the more obtuse technical talk. You don’t get that experience straight out of school.

That doesn’t mean someone whose first job out of school is as a technical writer will be bad at it. There are good writers everywhere.

It doesn’t mean that technical writers are the only one with this problem either. An engineer or an accountant straight out of university is the same, and they all—engineers, accountants and technical writers—go on to gain experience. But until now, we haven’t had inexperienced tech writers. Almost without exception they have come from other fields first.

I am noticing more job advertisements for technical writers that specify some form of writing degree as the main qualification required. I also notice that undergraduate writing courses now often have a technical writing component, and that the institutions that run them are more open to, and pushing, technical writing as a potential career for writers.

I wonder how long it will be before we start insisting that technical writers must have a writing degree. An undergraduate writing degree.

Let’s face it. Sometimes technical documentation can be downright boring.

Sticking to the facts—just the facts—does tell the reader what they need to know, but do they retain it if it’s presented this way? Not normally.

When information is presented as an impersonal list of facts most people simply turn off. Or they use the material as a lookup for when they want to know a specific detail. When they’re trying to learn something they need more. That’s what makes the Dummies series and other books like them so popular.

I have used the Dummies series myself with varying degrees of success. I know people who love them, and others who hate them.  I’m a big fan of the Head First series myself, and they invoke a similar range of reactions.

When I want to get a message across I try to use graphics where I can. At work I occasionally use cartoons to get my message across. I can’t draw, otherwise I would use them a lot more. Or I will start with a graphic, say a screen dump, and add notes to the graphic so that the user has to read the notes on the graphic.

Both of these are more effective at teaching new users than step-by-step instructions.

The modern trend is for graphics and video to demonstrate new concepts. It’s being done less and less with words now, but it can still work if it’s done properly.

Designing an Authentication System: a Dialogue in Four Scenes was written by Bill Bryant back 1988 to explain how the Kerberos token ring system worked. It was updated in 1997 by Theodore Ts’o. For a document that’s 20 years old—and that’s ancient in IT terms—it does a pretty good job of explaining a complex technical subject.

I have spent a lot of time formatting documents lately. Taking information from, say, a Word document and turning training documents, taking information from SharePoint web parts and turning them into documents, converting training courses into procedures, and so on.

“Ahh,” you say. “You should be using single source. You should be using something like DITA to do this.”

And yes I should, but …

• I am the only person in our company who knows what DITA is, let alone knows how to use it
• I am the only person in the company who would ever write/read documentation in XML
• Our company provides Word and SharePoint as our document management tools.

You often hear good reasons for converting to a single source system, but sometimes there are also compelling reasons against it as well. You need to consider these before you race in.

Ask yourself:

• Who is going to manage it when you are gone? If the next person is going to convert it straight back to Word, why bother in the first place?
• Are you changing it just to keep up with trends or can you justify the need for change?
• How much work will it save you? More importantly, how much work will it save the company as a whole?

I know a single source of content will save me a lot of work. But for other people in the company it won’t. It will mean more work for them, not to mention a very steep learning curve, an investment in software and a strong training committment. It will save me lots of time and effort—in the long run—but it’s going to double the work effort of ten other people.  Where is the benefit?

Not only that, our company already has a decreed policy—Word and SharePoint are the tools we use. Who am I to go against a company-wide policy (that works, incidentally), without a truly convincing case?

I work with developers. For the developers at my work the only way to share knowledge is via a wiki. It takes a lot of time and effort to convince them that they can’t implement their own open source wiki, that they must use SharePoint as their reference tool. (MOSS is coming, but it’s not at our company yet.)

I would be a hypocrite (not to mention lose all credibility) if I suddenly started doing my own thing documentation-wise.

My working life revolves pretty much around Microsoft.  Over 90% of my work is done in either SharePoint or Word.

Microsoft has a lot of information on their sites about these products.  Unfortunately, I can never find it. I usually only know it’s there when I stumble on it months after I really needed to know it.

Their sites look good, and once I know what I am doing I can see that it also contains truly valuable information. The only problem is, when I don’t know what I am doing I have no idea how to actually use the information that is there.

The steepest part of the learning curve is at the start.

I really struggled with SharePoint until I learned one simple basic fact. There are two programs. Until I grasped that there were two programs, that one sat on top of the other, and that they both did slightly different things, I was forever trying to do things that wouldn’t work. For example, I read in the SharePoint Help, and in online forums, about how you could set document or list level security.  I was using SPS 2003, and I tried and tried, and I could never do it. Because you couldn’t, in SPS 2003. All the instructions were for WSS,  but because I had not yet grasped the two-program thing, I thought they were just talking about SharePoint as a whole.

Likewise with another program I use occasionally—DITA. DITA is an xml schema used for writing documentation. I’m fine with the concept of a schema. I know quite a lot about DITA now, and can write pretty much anything using DITA schemas now if I want to.  But have you ever tried to set a DITA system up on your own PC? The DITA Open Toolkit gives you good information. They even tell you how to set it up and give you the files to download. Even so, I am still on that slipperly steep slope right at the start—how do I set it up on my system, what do I need to do to make it work?

A total beginner has different information needs to an experienced user. The experienced user needs exact technical detail about specific items. Point them to the right place and if it’s organised in any logical sequence they will find what they need. 

The beginner doesn’t know the information exists, they don’t know where to look and they don’t even know what to look for. They need big picture stuff, but the things that trip them up are not even always about the system itself. With DITA, for me, it was setting DITA up to use. With SharePoint I knew more than enough about libraries and lists before I had any real knowledge of how to use them in the business. And, as I said, the two program thing was a big knowledge hurdle.