Technical Writer

First impressions:

It’s a smaller group than previous years. Obviously, the global recession is biting hard on the conference scene.

Structured authoring is still big, but the tools that you use for structured authoring (xml and schemas such as DITA) are now pretty much an accepted part of the landscape. There is a lot of talk about different mediums, not just paper. Paper-based documentation isn’t extinct just yet, but it’s heading that way.

Globalisation and associated regionalisation of material is being talked about more and more. This is a trend I have noticed outside the AODC as well. A lot of companies are creating one product world-wide, and one set of documentation for it, and then getting people to translate it into other languages for the region.

There was discussion as to where products like technical documentation fit in nowadays, how users search for help and so on. (As usual, the on-line help/user manual comes a very poor last.) Interestingly enough, this too is brought out in my own work experience. The company I currently work for ditched their on-line help (RoboHelp .chm files) around four years ago. So far as I know, they haven’t had a single complaint.

Overall, the conference seems less technical than in prior years. It contains a good mix of topics. (I love the technical stuff, myself, but I can see that most writers would prefer this year’s mix.) It feels slower paced than in previous years. I’m really enjoying that.

In Gerry Gaffney’s last session of the day we looked at why people become tech writers and whether we were happy in our jobs. On a scale of 1 to 5, where 1 is truly miserable, 3 is so-so and 5 is ecstatic, we rated ourselves an average of around 4.2 (give or take a couple of points). I’m not sure if this says tech writers in general love their jobs, or just those at this conference.

At my work we run information sessions, where we ask people to talk about something they are working on, an area they have expertise in, or tips and techniques they use in their work. The one group of people at my work who don’t share knowledge well are those at the grass roots level—the developers, the system architects and the technical writers.

It’s not that they don’t want to share information. They do. They will happily talk one-on-one or in small, informal groups about the very topics I want them to cover. But as soon as I ask them to do a presentation—and these are very informal presentations—they panic, and find excuses to not do it.

It’s not easy standing in front of a crowd of 30+ people and talking. I, personally, have enough trouble at some meetings, let alone in a larger crowd. But as those of us who have ever been thrust into a training role know—you get better if you keep doing it.

You may never be as good as someone who has natural talent, but you’ll get by. You’ll do a competent job. (Sadly, you also get worse if you stop doing it.) One girl I know got so good at it she got a promotion out of it.

And yet, if you can do it, you really should take these opportunities. There are career benefits:

• It raises your profile as a subject matter expert
• This in turn raises your profile in the company and makes you more valuable (translated, less likely to get the chop when the axe falls)
• And if you do lose your job, you should be more relaxed presenting in front of future prospective employers.

There are so many advantages it’s hard to think of any real disadvantages.

Even so, it’s still traumatic for many people.

There are things you can do to prepare yourself.

• Be prepared. I don’t say you have to plan every talk down to the second, but you will be less stressed if you know what you are going to talk about before you get up. Practise on someone if you can. I ask family and friend to listen. Their eyes glaze over, and sometimes we get bogged down because they don’t understand the technicalities, but it’s still good to run through it. If you can’t find someone to listen, just practise anyway.
• Accept that being nervous is normal and try not to be too stressed about it. It’s easy to say, I know, but try.
• Likewise, understand that the first time you ever do this (and the second, and maybe even the third) you will probably muck it up. It’s not the end of the world. Accept it and move on. You are the only one who really cares how badly you did. Most people haven’t even remembered it half an hour after the presentation.

Lastly, once you agree, don’t talk yourself out of doing the presentation; don’t get so nervous that you back out at the last minute, or call in sick. If you agree to do it, do it.

As the organiser of many of these events, I can tell you it takes a bit of work to set up, even when they are informal, and I know how my perceptions of people change when they cancel at the last minute for no good reason. In fact, I have one colleage at work—brilliant at what he does—who has pulled out on me three times, very close to the function. He’s one very smart man, but I have absolutely no respect for him at all now. How I feel about what he did at those functions colours how I feel about him as a co-worker, and about him in general.

So if you do get asked to present something, don’t panic and automatically say no. Consider it seriously and say yes if you can.

It’s not as hard as you think it is, and it might be very good for your career.

I recently bought a Livescribe Pulse Smartpen, and was quite impressed with the way the documentation and help was integrated into the product.

The smartpen is an electronic pen that records both sound and text strokes as you write. It uses an infra-red camera and special paper printed with a grid of dots that tells the computer inside the pen where it is at any specific moment. You can tap on your notes on the page to replay the sound recorded while you were writing that particular text. It works in conjunction with software that you load onto your computer, which you use to store and replay your notes—audio and text. It’s ideal for taking notes at meetings and lectures, and this is where it is marketed.

By its very nature it makes for some innovative documentation methods and Livescribe have used these well. Each part of the documentation is simple enough, but combined they add up to a whole that really impressed me. By documentation here I mean audio visual. I’m not just talking written documents here but how-to videos and so on.

The pen comes supplied in the box with the following documentation:

• A single sheet giving the URL of the support site to download the associated desktop software
• A quick-install guide—again, pointing you to the web site
• A fold-out sheet containing brief intstructions on how to use the smartpen
• A journal. This journal is the actual book you write in, but it also contains some documentation

Outside of documentation the package contains the pen itself, a USB cradle that you use to connect the pen to your PC, a headset and some accessories (e.g. extra nibs).

The USB cradle had a paper sticker around it telling you not to plug it into your computer until you had installed the desktop software. You had to tear the label to unwrap the cable. This is probably the best example I have seen in a long time of preventing you from doing something that you might otherwise instinctively do—in this case, plug the USB cable into a port on your PC before you were ready.

The installation instructions were a small, double-sided sheet of paper. They were simple. Go to this page, and to download your desktop program.

Once at the site, an ‘Introducing Pulse’ video starts playing. It’s only 15 seconds long, and its main function is to point you to the other four videos that you can watch to show you how the smartpen works.

While you wait for the download to finish (big, clear buttons for this, and clearly differentiated from the videos) you can watch the four training videos. They’re short, around a minute for each and cover:

• An introduction to your smartpen
• How to set the date and time
• Using the headset
• How to use the desktop program.

This is really all you need to know to start using the smartpen. I like the way you don’t have to move away from a single screen to learn how to use the pen.

But if that was all, I might have said, “Well, that’s nicely done,” and thought nothing more of it.

But Livescribe’s piece de resistance is their journal.

The journal that comes with the pen is a tutorial as well. They devote two pages of the journal to tutorials. They give written instructions on what to do, and you use the pen to practise what they’re talking about.

The bottom of each page contains standard control functions. On the two tutorial pages, these functions come with an information ‘i’ above them. Tap on the ‘i’ and the smartpen tells you how to use that particular function.

It also comes with with an interactive demo card. This is the size of a credit card and the front contains three graphics which you tap on to see two small films (it’s amazing how much you can video you can pack into a 96×18 pixel display) and a demo on the stereo headphones. The back of the card contains a demo of the translation component, and also shows you how to draw up a keyboard and play it.

I didn’t have any problems following any of their instructions, and playing around with the tutorial pages and the demo card gave me a good feel for the pen and how it worked. I felt comfortable using the pen very quickly.

Obviously the nature of the tool allows for some good interaction between the tool and the documentation. Even so, it is an impressive blending of tool and help. I think they have done a good job.

Over at EndUser SharePoint.com, Lee Reed talks about a new term shetiquette, or SharePoint Etiquette, and lists some things that are just not etiquette, like checking out documents and not checking them back in, entering garbage in meta-data fields, not providing training and so on.

He (or she) separated the list into two parts—one specific to users, the other to SharePoint administrators. They’re all good points, definitely worth a look, but the two that really resonated with me today were points numbers 10 and 16 in the adminstrators/site owners area. These were:

• Trying to “protect people from themselves” by blocking features in SharePoint rather than enforcing existing corporate policies for the proper use of corporate technology systems
• It’s also bad Shetiquette to give people the additional responsibilities of managing their Department’s SharePoint site without adding the responsibility to their job description so it will be considered during their performance evaluation.

Protecting people from themselves

Probably one of the biggest mistakes we made when we first set up our SharePoint portal was to set up as much as we could read-only.

While some areas definitely should have restricted access, we restricted way too much. The problem was, we then had to dole out individual access for users to even add documents to libraries where appropriate. (Another big mistake here was that we gave individuals access, not groups.) So after a while every different sub-site had different access. Then people would leave, and they’d be pulled off the Active Directory, but their names were still on SharePoint sub-areas (this was 2003 version) and we couldn’t get them off without a fiddle because they were no longer on active directory, and so on. It became a real mess.

Not only was it a mess, it prevented people from using SharePoint properly, because they really couldn’t do anything except read documents.

It took us a long time to realise that we already had corporate policies for who could do what and where. We didn’t have to do anything special for SharePoint. All we had to do was apply our standard policies across SharePoint as well. When we finally worked that out managing users on SharePoint became much easier.

It took a lot longer to really get people using SharePoint, however.

Adding SharePoint responsibility to the job description

This one particularly resonated with me because right now at work we are undergoing our annual performance reviews. We have just completed last year’s and are also kicking off the 2009 process. As the SharePoint administrator SharePoint is included in my performance evaluation, but I guarantee I am the only one in the company who has it.

We put all our business processes, policies and procedures and compliance documents on SharePoint. The people who are in charge of these documents are also responsibile for the SharePoint site where the documents are stored.

Making managing the SharePoint site part of these users’ job description would give this work a higher profile. People would be aware of it. Their managers would be aware of the work they do. It wouldn’t be considered dead time any more. People would pay more attention to what they do and thus it would be easier for them to attend training and other SharePoint-related sessions that could help them to do a better job.

We’d have a better site, and the site managers would be a lot more SharePoint savvy.

My first attempt at single sourcing was way back when Microsoft Word introduced master documents and sub-documents.

It was a wonderful theory.

Create a bunch of smaller documents, combine them as required for various audiences, and voila, the perfect single-sourced document.

Anyone who used master documents back in those early days would know what happened.

That part of the Word program was really buggy. Word crashed, documents wouldn’t open, files got corrupted. It was an absolute nightmare.

We abandoned the idea after we lost a course-load of training materials and the associated help manuals. (This was back in the days when we printed everything on paper, even the help.)

I haven’t used Word master documents since. In fact, as I was writing this blog I had to check to see if they were still included in Word 2007.  (The closest equivalent I can find is quick parts and building blocks, but I have never used them.)

Single sourcing is touted as a ‘new’ thing, yet people have tried to use it for a very long time. It’s only now, when the technology and tools catch up with the user’s needs, that we can really use it properly.

The lead time for some of these technologies can take a lot longer than you think.

Another project I worked on back when I was a developer—and I have been a technical writer for a very long time now—was an online shopping system.

By today’s standards, it was unusable. The shopper set up an account with the company, then plugged a special keyboard into their phone line and television, and ordered using product codes from a printed handbook. The line often dropped out half-way through the order and the only thing the poor user could do was dial up and enter it all again.

It took two years to build and I honestly wondered whether on-line shopping would ever take off.

Look at us now, where half the things we buy are on-line, and you don’t have to build shopping systems any more, you purchase shopping cart plug-ins from other vendors for a minimal amount.

Likewise with single sourcing.

Ten-fifteen years on from my first attempt at Word master documents the tools are ready for single sourcing. So what has always been a good idea now becomes doable. And practical. And even a buzzword.

It will be interesting to see where we are in another fifteen years.