Technical Writer

At a recent function the speaker, Rob Thomsett*, mentioned that he hated overheads and refused to use them. He then proceeded to give an entertaining, one-hour speech with his only prop the microphone he used so we could all hear him.

The day after Rob’s talk I went to a meeting on standards.

This was supposed to be an informal initial discussion, but the co-ordinator used overheads to denote major topics. While there was nothing wrong with his use of them, the overheads made the whole meeting a lot more formal. He could have used notes instead, and introduced the topics that way, which was more in the planned spirit of the meeting.

At the time I was running a series of three-hour workshops. At these workshops I used overheads interspersed with practical examples.

The overheads provided an introduction to each topic, and some memory joggers for when the participant went back to their desk. However, this meant we were constantly switching between the overheads and the system I demonstrated.

The next workshop after Rob’s talk I decided to do away with the overheads altogether—except for a few introductory ones at the start and some closing ones at the end.

It worked well, and I use this technique all the time now for these workshops.

“So what,” you might say. “Everyone knows most people overuse overheads.”

While we all want to design perfect materials, the fact is that we don’t. We work to deadlines and don’t always have the luxury of creating perfect material. If we’re a lone writer we don’t have anyone to bounce ideas off, to suggest there may be a better way.

It’s easy to slip into bad habits without realising.

Sometimes it takes a chance remark, like Rob Thomsett’s, to make us reassess how we do things.

That’s always good.

---

* Rob is a great speaker, and knows a lot about project management. I highly recommend that if you ever get the chance to hear him speak, take it. His Rough Rules of Management include “You know a project is failing when you can’t stop it”, which contains some truths that most of us would nod our head over.   

Having a good resume obviously helps your chances of getting a better job, but what do people look for in the resume, and is it any different for a technical writer, for whom a resume, really, is just another form of writing?

There are hundreds of books and web sites and courses that tell you how to write a resume. I am not going to do that.

However, I have employed a number of staff in my time, and I thought it might be interesting to show one person’s view from the other side. What I, as a potential employer, look for in the resume, and what conclusions I make about the person who wrote it.

Other people may—and probably will—do it differently. This is how I do it.

[Note: Yes, I have deliberately left the acute accents off the é’s on résumé. It is, technically, a typo, but getting them to display properly on everyone’s browser is a pain, so I have left it as resume. Just don’t do it on a resume you send to me though. I treat them as typos.]

First, and most important, is to get a copy of the writer’s original resume.

Most technical writers come through an agency. The agencies often rewrite the resumes to suit their own standards (or maybe to suit what they think the customer wants, I’m never sure which). It is often quite hard to get a copy of the original. We had to train our agencies to do it.

Once I get the original resume, here’s what I look for:

• The writing, obviously—basics like spelling, grammar and use of words. Any errors here denote sloppy editing.
• Does the applicant write well?
• Is it easy to read. If I have to re-read something three times before I understand it, this tells me the applicant can’t write, or is poor at revision.
• The applicant’s work history is obviously important. If the agency got it right, the work history should reflect pretty much what I have asked for.
• What does their resume look like? While I don’t expect technical writers to be graphic artists I do expect them to understand how important it is to produce tidy, readable material. The document should also look professional. Pale blue paper with gold angels in the background gives just as bad an impression as a resume where the infomation is squeezed into the top half of a single page. (To be fair, these two examples wouldn’t get past the agency, but you get the idea.).
• Have they used consistent styles? A document that has one blue, 18 point Times Roman heading and the next—same level—heading red, 16 point Verdana is going to tell me that if this writer can’t even manage to make their resume consistent they are not going to care about the finish of documents they produce. Someone I can’t affor to use on my team.
• Have they used styles? If I get the resume as a Word document I will also check whether the applicant manually formatted each line or used styles. Manual formatting is not something I like to see. It doubles, and more, the time required to update documents.

These are the basics. Then I start looking at some of the more nebulous aspects. The gut-feel, if you like. These are very personal, and each person has their own list of gut-feel items.

• Is their writing style compatible with the project/company? This is not always evident in a resume because it is, after all, a sales document, but you can usually get a feel for the type of writer the applicant is. A more formal style of writing might be suitable for a larger company, while a less formal style is more suited to my own contracting business.
• What are their interests? This one is personal. I am the only interviewer I know who does this, but I always like to see writing listed as an interest for a technical writer. I believe that someone who is passionate enough about writing to list it as an interest is probably going to be a better writer, and more likely to care about the end result, than someone who doesn’t. Of all the people we have employed to date, this has turned out to be the case.

Remember, the ultimate aim of the resume is to sell yourself. Even if you hate sales, it’s what you have to do to get a new job. The technical writer has two sales tools.

“But,” you say, “I hate sales. I’m a lousy salesperson.”

Most of us are, but unfortunately we still have to do it. It’s the way life works, and refusing to partake of the sales process is your loss, no-one else’s. No matter how good a technical writer you are, if you can’t prove to me that you are good, you won’t even get an interview.

There are two parts to the selling process—the foot in the door (the resume) and closing the sale (the interview).

Technical writers have two tools for the foot in the door process. One is their work history, the other is the resume itself. Produce a decent resume that showcases your writing skills, and you’re half-way to the interview already.

Using tables to create web pages appears to be a thing of the past. Since the advent of CSS divs are king and the humble table used for page design appears to have gone the way of the dodo.

Back when I started creating content for web pages we put everything into tables.

If I wanted a three column page with a menu across the top, links down the left-hand side and additional information highlighted at the right I would create a table as follows:

Main menu Option 1 Option 2 Option 3
Secondary menu         Sub Option 1 Sub Option 2 Sub Option 3 … Sub Option n	Main body of the page goes here	Highlighted part here

and put my HTML directly into the table cells.

It doesn’t work like that any more.

True, there are still thousands of sites out there using tables to display their data, but the advent of CSS and divs and spans has heralded a new era in web design.

The www.csszengarden.com site shows the way.

The Diary, by Alexander Shabuniewicz is totally different to, say, Ray Henry’s Zen City Morning.

Exactly the same HTML data is displayed on both pages. The only thing that has changed is the CSS that is used to produce it, and the pictures.  The underlying page has not been touched.

(Those of us who use Word Press might recognise similar functionality through the use of themes, but it is not the same. Wordpress themes often do change the underlying pages, these do not, they are totally driven by the CSS.)

What does this mean for technical writers?

Firstly, the content is totally separated from design.

This means that you can concentrate on what you are good at—writing the words—and let someone else worry about the look and feel.

Secondly, it allows reusability. All you need to do is produce a document once.  It can then be badged according to each company you produce it for.

One set of proofing, one set of reviews. The only thing you need to duplicate is the final copy, when you attach the appropriate company style sheet.

Everything is controlled from the stylesheet.  Everything.

Yes, you can get the same effect by creating tables in the HTML and placing your data onto the HTML page.

Using tables is actually a lot simpler.

I really struggled to set up the divs on our home page www.infinitediversity.com.au, for example. I was tempted to go back to tables because I knew it would work. I knew I could be finished in an hour, instead of the four hours it took me to get it right (and it’s still not 100%), but if I ever want to change that page now all I have to do is replace the current stylesheet. I never have to touch the home page again.

Combine this method of displaying pages totally via the style sheet with a single source of content such as XML (DocBook or DITA standard) and you have one of the holy grails of technical writing—single source content.

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.

XML is the future.

You hear it at every conference you go to, in every magazine you pick up, in every article you read on-line.

For technical writers, right now that future comes down to two products—DocBook or DITA.

But what exactly are they, and which one should you choose?

They are schemas for creating XML.

What are schemas?

Think of them as blueprints, or templates, or even stencils. They are rules that tell you how to set up the xml.

The rules might be, for example:

• You must have a heading
• You may have a sub-heading if you wish, but it’s optional. If you do have a sub-heading, it must go immediately below the heading
• You must have one or more paragraphs of text
• You may include instructions. If you do include instructions they must be at the end. You should not include step numbers.
• You can add links to paragraphs or instructions, but not to the heading or sub-heading.
• Likewise, you can make the paragraphs and instructions, or part thereof, bold or italic, but you cannot make the heading or sub-heading bold or italic.

That’s a simple schema.

You may also come across the term document type definition (DTD). It’s a similar thing. Document type definitions are being replaced by schemas.

As a technical writer, how do you use DocBook or DITA then?

You write your documents in XML, making sure that the XML fits the DocBook or DITA schema.  Then any transformation file built around the appropriate schema can be used to produce end-user materials.

Why bother?

There are so many reasons but the main ones for technical writers are:

• Consistency, and
• Single source for multiple output.

For example, in the on-line help produced from the simple schema above you may only use the title and the instructions. In this case, the transformation file will only pick up the title and instruction elements from the XML. You may also produce a user manual which uses the title, sub-heading, all paragraphs and the steps.

You can use the same XML to produce the user manual both on-line and as a hard copy.

Likewise, all you need to do is change your style sheet and you can produce the help, an on-line user manual and a printed user manual for a different company.

The possibilities are limitless.

But what about DocBook and DITA?

You can create a schema from scratch, or you can use one that someone else has already set up for you.

DocBook and DITA have already been set up to do exactly what we do as technical writers. Rather than spend lots of time and money inventing something so similar to either or both of these, many technical writers have adopted one of these schemas as their standard.

DocBook was implemented by the publishing company O’Reilly & Associates and is particularly suited to books, in particular computer books.

DITA (Darwin Information Typing Architecture) was implemented by IBM.  It is more suited to tasks or topics, such as on-line help, or procedures.

Thus if you write book-length documents, consider DocBook. If you write chunked information, consider DITA. If you write a combination of both, the general consensus seems to favour DITA for this as well.