Technical Writer

A developer came to me today and asked me to check his xml against the schema he was writing it to. It was exactly one week since I had offered to check it originally. He had struggled with it in the intervening seven days, trying to work out where his code didn’t match.

It took two minutes to find the three places where the xml didn’t match the schema. He could have found that out seven days ago.

It is common among both developers and technical writers who work with xml to look on schemas (the XSD files) as a necessary evil. Something they grudgingly have to accept because it’s been directed from high, but not something they would use if they didn’t have to. They do their coding, or their writing, first, and then try to force it to fit the schema.

If you are one of these people, you’re doing it all wrong.

Start at the other end. Start with the schema. Write always with the schema in mind. Don’t even think of starting your work until you understand what’s in the schema and how it fits together.

XML-Spy does diagrams of schemas. I offered that same developer a diagram. “No,” he said. “It’s not necessary. I’ll work through it.”

This was a fairly complex schema he was working with. One of those third-party data feeds that we take information from, transform it, and put it into our system.

“Fine,” I said, but I have to admit I thought he was making the job unnecessarily hard.

You might think it strange that I am picking on developers in a technical writing blog, but let me tell you, a lot of tech writers have the same attitude. The same people who happily accept that a style manual is necessary, and that a document template is compulsory, consider the schema a nuisance—something that makes their job harder, restricts their freedom and adds extra work.

It’s not. It makes your job easier. Now, when you are writing the initial documentation, and definitely later, when other people are updating it.

But … you have to start with the schema, not with the document.

Let’s take a practical example.

Below is a diagram of a very simple schema. Dotted lines mean an element is optional, straight lines mean it is compulsory. You don’t get schema diagrams everywhere, by the way. The xsd file is just text—a special xml file, but if you can get a picture of the schema it’s going to help you enormously. If you want to see the original schema, it’s here.

DITA users will notice I tipped my hat in their direction with the tasks thing, but comparing this schema to DITA is like saying the scooter a child rides to school is like an 18-wheeler truck. They’re both transport.

What can you tell me about this schema?

It’s pretty basic, isn’t it.

There is an outer node called task, with three attributes (all compulsory), an optional introduction, some steps, and then an optional conclusion. The introduction and conclusion are one element each, so you know immediately that there’s no point writing reams and reams of introduction.

The most important thing to see from the schema is that there is room for only one paragragraph in the introduction and conclusion. If you know this before you start then you won’t bother writing a whole page of introduction which you later have to cut down.

Likewise the steps. Each step is a single paragraph and there is no bold or italic or any other emphasis. (I know, it’s unrealistic, but it’s only an example.) From this you know you can’t have big, long-winded steps. There’s no room for graphics either. Write simple steps. Anything else and you’re going to have to rewrite. So don’t write it to start with. The end result looks something like this.

If you follow the schema guidelines, it’s not hard to set up each task. If you write the task first, and then try to fit it to the schema, you’re bound to have problems. Just like my developer friend, who persisted, despite everything, in writing the code first and then trying to make the code fit the schema. If he’d written the code to match the schema it would have saved him seven days, probably more.

The schema is your friend. Stop thinking of it as a necessary evil and start thinking of it as the time-saving device it is.

Nice job by Google of documenting their Chrome browser.

The blurb on the page that links to the documentation says

Look under the hood of Google Chrome in this comic’s interpretation of key engineering decisions …

and they have delivered exactly what they promised.

As a piece of technical documentation it’s fun, it’s interesting, and it packs some real information in there (and you get a glimpse of who was in the team).

You can pick the audience by their blurb when they talk about ‘key engineering decisions’, so I know immediately it’s for developers, engineers, and people interested in programming and web technology generally. It targets that audience well.

The format, media and delivery also mean that a less-technical user can still get some value out of it, and enjoy reading it, even if they don’t understand all the technical references.

Most of all, it’s fun.

Nice job, Google Chrome Team and Scott McCloud.

Our workplace is undergoing major staff transitions at present. A lot of experienced people are moving on and trying to pass on their knowledge in a hurry. A few of them have done so by creating videos—they’re mostly screen captures with voice-overs created in something like Camtasia or Captivate.

I mentioned one series recently, where the developer had created videos that ranged from half an hour to an hour and a half.  Based on the knowledge handover work plan, by the time this person has transitioned this particular piece of knowledge, we’ll have 12 hours of .avi files and 18 videos.

Each video uses the same piece of software—which this developer wrote—to complete different transactions.  Some fields in the different transactions are the same, others are different. If the developer has already covered a field in a previous video session, he omits explaining it in following sessions.  (Which is a good thing really, because otherwise we’d have 30 hours of videos.) Interspersed with instructions on how to carry out each transaction is general knowledge about each of them. This man knows his product. He knows his transactions, and he’s passed a lot of it on.

This is very specialised knowledge.  Vital for a small number of people in the company to know, but not really interest to others.

They’re very rough at present. He just sat down and talked while he worked through the scenario, so they include comments like “Oops, that didn’t work, did it. Let’s try it this way,” and repetitions, and lots of thought trains started but not completed. They’re also very badly taped. He has a 22″ monitor, which was set at the highest resolution. I can’t even see the full video on my screen. I have to scroll.

I can make some excellent on-line documentation out of what he has given us, but to do that I would take his voice-overs, tidy it up, reorganise it into something logical, and re-shoot the screen-captures.  It would take me at least a solid month of work and then five, maybe six people would use it once, and then dip into it occasionally for information they can’t remember.

Given the small audience, how much work should I do to tidy these videos up? Is it worth a month of my time when I can spend that time documenting something that more people can use.

This is important information, but where does the effort to fix it cross the line where it’s not worth it to do?

If I don’t fix it, how much work should I do to make it at least useable?

Here’s what I know:

• No-one at work, not even those who have suddenly become the subject matter experts for this area, is going to sit through 12 hours of videos. I have already asked them if they are prepared to do so, and they have said they won’t
• .avi files are not searchable. Yes, I can include metadata, but all those little snippets of useful knowledge about the product that are hidden in the videos will remain hidden unless I can put it into a searchable format. (I tried third-party voice-to-text software but it was hopeless in this particular case, and we didn’t have the developer any more to train the software)

At present I am thinking that what I might do is:

1) Create .MP3 files from the videos and make them available alongside the .avi files. 

Users listen to these podcasts in the background while they are work on other things.  Obviously, you lose something not seeing the screencast, but given that each transaction uses the same set of screens you would have a fair idea of what is happening. It’s also a way to assimilate all those hints and tips that are general to the topic, rather than to the screens.

2) Transcribe the podcasts onto paper

This is a big job, but at least it makes the content of the video searchable. This means that a user looking for specific information on that particular topic at least has a chance of finding it.

If I include times the user can then open the video if necessary and go direct to the part where the topic is covered.

3) Split the videos

Optionally, I could also split the videos into sections, so that if a user wants to access a specific section of the video they can get to it more quickly.

Outside of that, I’m still considering what else I can do to make the information more accessible without wasting too much time on little-used information.

I have spent the last two weeks switching between Captivate and Camtasia Studio. Talk about schizophrenic. I spent a lot of time trying to remember which command I had to use in which program, but overall it’s been an interesting experience.

For those who are not familiar with either program, they are both programs which allow you create screen-based learning modules. I’d call them eLearning tools.

The marketing material doesn’t always say what a program does, but here is the publisher blurb for each:

• Camtasia Studio gives you the power to easily record your screen, PowerPoint presentations, voice and Web camera video to create compelling video tutorials, training presentations and rich sales demonstrations for web and CD-ROM delivery. (TechSmith)
• Adobe Captivate 3 software enables anyone to rapidly create powerful and engaging simulations, scenario-based training, and robust quizzes without programming knowledge or multimedia skills. (Adobe)

Some history

Captivate started out as a product called RoboDemo, produced by a company called eHelp, whose most famous product was … that’s right … RoboHelp*.  eHelp was bought out by MacroMedia, who changed the name RoboDemo to Captivate and added some new features. Macromedia got bought out in turn by Adobe, who added more features.

Camtasia Studio is produced by a company called Tech Smith, famous for one of the handiest pieces of software I have ever used—a screen capture program called SnagIt.( If you have never used SnagIt, I recommend that you try it.)

I started using Captivate a couple of years ago, after a Macromedia consultant gave a very enthusiastic demonstration of its properties.  And I found it good. I am currently using Captivate 2, which is one release behind the current version.

I was first introduced to Camtasia Studio by a colleague who had downloaded the demo version, created a couple of video files (.avi format) using it, and then wanted me to turn them into eLearning modules for him. He refused to create the videos using Captivate (of which the company had a full copy) and I couldn’t do much with the AVI files in Captivate so I ended up downloading a trial version of Camtasia Studio and managed to tweak the files enough to produce something not really good but okay enough to get by.

And there I was until two months ago, when a contracting company for whom I do occasional work asked if I would create some screen demos. I agreed, but because this was weekend work, outside of my permanent employment, I needed a program to do it with.  Camtasia Studio costs US$298, while Captivate starts as US$699. It was a quick, cheap contract, and wasn’t even going to make $700.  You can guess which one I purchased. 

Two weeks ago the colleague who had created the original AVI files started producing training material (under contract). I don’t have any control over what he produces—and naturally, he’s producing AVIs. So far he’s created six hours of it, and by my calculations he’s only half-way through. Not to mention—they’re huge.  One of the videos comes in at 500MB.  I can’t even load them onto the website. We had some animated discussions about it. In the end I agreed—he could make the videos as he wanted (it was the best use of money versus his time) and I would do something to them to make them at least useable.

Continue reading