Tag Archives: XML

Is structure about code or about content?

by

Here’s a short one, cause I’m writing on a train to Nuremberg…

When writers are not used to structured authoring and have to adopt a standard like DITA, they tend to blame DITA and the new tools for complicating their lives. In the new process, the first thing writers notice is that they have to use elements they are not familiar with, and that there are various ways to use them.

Unless they go through training on structured authoring, they start with the wrong plan, that the unstructured text (and thinking) would just have to be mapped to the new structure, as “structure” would be about code, not about writing.

Indeed, the XML code sets a valid structure to the topics, but there is more to structure than applying DITA elements. Documentation can benefit from the principles of structured authoring even without adopting a certain standard. You can do your project research and information model, define your own house rules and styles, to provide consistent, minimalistic, reusable documentation, in almost any authoring environment.

Do not blame DITA or the tools, that you have to structure your procedures or your lists of parameters in a certain way. Ideally, you would have seen the need for that structure before, and thanked Heaven (or the DITA committee) when the standard came and you rushed with the business case to your team and managers.

Happy DIT’ing!

Be an XML writer and proud of it

by

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…