Technical Writer

I spent the last three days at the AODC.  Lots to think about, which I may cover in other blogs, but here are some general impressions.  Of course, these are my own impressions, and it may be just who I talked to on the day.

• There are plenty of tech writing jobs out there at the moment.
• The role of the tech writer is changing along with the technology we use to do it.  Adapt or perish.
• Globalisation is big.  More companies seem to be involved in translating to other languages.
• XML has arrived.  (As distinct from all those years where we have been saying it’s coming.)  People don’t talk so much about XML any more, they talk about schemas used to manipulate XML—DITA, DocBook, RSS.  And rather than talk about moving to XML (althought that’s there), they talk about moving to an XML schema based product, such as DITA.  
• Web 2.0 products are heavily over priced at present.  The prices paid for companies like You Tube and My Space are reminiscent of the prices paid for dot com companies just before the original dot com bust. 
• Tools are merging.  The tools you use to manage documentation may be different, but behind the scenes the way each tool does it is similar.
• The new front end programs are most often accessed through a browser now. Even if they are not, some form of web interface is built in.
• Single sourcing and content re-use are the way of the future. 

If you haven’t seen single sourcing or XML coming, you probably need to do a little more reading in the field.  Both these have been coming for a while.

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.