Tag Archives: technical writing

The DITA Architect’s role

by

What does it take to be your team’s DITA Architect? Naturally, you have to thinkDITA, understand Information Architecture, use DITA for some time and know what you can do with it.

If in addition to being a DITA Author, you find yourself addicted to it, like there were no other way to do technical communication, if you read and try out all ideas you can find about DITA and related tools, then… you’re on the right path to being a DITA Architect.

There is one more thing, though. As I learned from Eliot Kimber (@drmacro), there is a difference between a geek and a nerd: the geek likes to talk about his nerdiness.

If you’re serious about the Architect role, you know it’s not enough to set up the authoring environment for the Writers in your team, especially if they are new to DITA. Apart from someone dealing with tools configuration, XML, XSLT, XSL-FO, CSS, jQuerries and Ant scripts for them, what the team needs, is answers to their questions, assistance, guidelines, code reviews, and even more answers.

You may thinkDITA and breathe DITA, but as an Architect, you have to lead and inspire DITA.

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…