Technical Writer

On a project, don’t expect that just because you you are working to the same end, you will all be thinking the same way, with the same end goals.

A recent discussion on xml schemas served to remind me of this.

We were setting up standards for the passing of data as xml between two companies.

There was some initial agreement. We would use schemas, and if the xml failed the schema validation it wouldn’t get sent. But that was about it.

One party wanted the schemas to be as loose as possible. He wanted everything typed as extra-long strings, so that it never failed validation at all. He wanted the code at the recieving end to pick up any problems.

Another party wanted dates more specific, so that dates prior to the go-live date could never be sent.

Still another party wanted the xsd to be future proof. For example, each file has its own unique ID. We set this to a maximum of six characters—but what happens when we send the millionth file? (Given that we were only sending this file once a week, I suspect the software will be well and truly obsolete by that time. Not to mention that the schema would be the least of our worries. If the length was written into the schema it would also have been written into the code as well, and that’s where our most serious problems will be—in the code.)

Then you have the technical dreamers, who get sidetracked by technicalities. The xsd date standard is YYYY-MM-DD, or you can create your own data type if you wish. Not these people. They get carried away with a technical discussion on the relative merits of why W3C chose that particular standard when, say, YYYYMMDD would have been better.

We persevered. We got a standard, and it’s been pretty robust so far, coping with all the idiosyncracies people have thrown at it. The xml that’s coming from the various supplies looks consistent, and feels consistent. That’s all you can really ask from an effective standard, I think.

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.