Be an XML writer and proud of it

Why am I scared every time I hear or read about “easy” or “light” tools and standards for tech writers? Do we really need to scream out for compassion? Is technical writing that complicated?

Assuming that tools are complex and distract us from the main task, meaning actual writing: How should we see our job? From what I see around and on the Web, the message seems to be: “I’m a writer, I have an English degree, so I just have to be creative, write freely, without restrictions from standards or tools.

Reality check: The customer is paying for an immediate solution to a problem, not for reading our best essay. The employers pay us to deliver accurate, readable, findable, and timely information. So, setting aside that creative writing is not necessarily informative, we are required to work by certain standards and with discipline. We have to contribute to the business objectives, not to the national literary patrimony… at least not during business hours.

As for the tools or code, why wouldn’t we prefer writing some XML tags to apply semantic structure to the information, instead of pressing some buttons to apply just styles and then spending more time on tweaking the layout than we did on writing the text?

If the target users and the business model need to find and exchange the content on various devices, so be it. We can support them.

Instead of writing in a word processor “Place the cup on the tray and press Coffee“, then selecting “Coffee” and applying some style from a list, we can just as easy, or maybe even quicker, write in a plain text or wiki editor “Place the cup on the tray and press *Coffee*“.

Even better, in a text or XML editor, we would write: “Place the cup on the tray and press <uicontrol>Coffee</uicontrol>.” Now Coffee has semantic meaning, and can be rendered in whatever way the customer needs it. Might be bold, might be brown, might even be hot and smell like coffee, why not?

And why should we be scared, if we’d have to write “Place the cup on the tray and press <uicontrol keyref="btn_hotbeverage">.” so it can be reused by colleagues, by business partners, or even by the entire community, if we’re acting in the crowd-source spirit of the Internet (of people and things)?

One small step for man…