Technical Writer

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.

 

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.

The Content Wrangler’s 10 DITA lessons learned from Tech Writers in the Trenches really nails down some vital things you should know if you want to implement DITA. More than that though, you can apply the lessons learned here to almost any project, not just technical writing and not just implementing new software.

Every time I read it I am struck by how true it is. A couple of the lessons are particularly relevant to me, particularly with SharePoint—more of this in later posts.

One of the really great things about sites like The Content Wrangler, though, is the sense of community you get from reading about other technical writers. Sometimes it can seem you’re the only tech writer on the planet, the only person experiencing the frustrations and difficulties peculiar to technical writing.

Another site that makes me feel the same way is Creating Passionate Users.

Take a look at both sites. They’re good value, and it’s always nice to know you are not alone.

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.