Editor’s Note: This post has been written by Dr. Tony Self of HyperWrite. Tony will delivering DITA training during October at Cherryleaf’s training centre in London.
In the field of technical communication, an argument crops up from time to time saying that technical communicators shouldn’t have to know anything about XML, because writing is writing, and XML is coding, and never the twain should meet. Dissecting the argument, it appears that the underlying claim is “language first; technology and tools later”.
In many cases, it seems the logic gets a little lost. I have heard statements along the line of “if you can’t string a sentence together, knowing about XML elements and attributes won’t make you a technical writer”, as if those skills are mutually exclusive.
My first observation is that the debate is often poorly framed. XML is not precise enough a term; what does “knowing about XML” mean? XML is an enormous field, covering programming, writing, archeology, journalism, eLearning, spacecraft design, mathematics, chemistry, audio recording, banking, gambling, engine management, and pretty much every field of human endeavour. So in a discussion about the role of XML in technical communication, we need to define what we mean by XML. Bearing in mind that XML is principally a standard for creating XML languages, the XML languages (or applications, in XML terminology) of interest to technical communicators are probably DITA, DocBook, XHTML, SVG, MathML, and XLIFF.
But even if the argument is re-framed as “technical communicators shouldn’t have to learn how to code DITA”, the point is still missed. DITA is a writing tool, not a coding tool. In the same way that a 19th Century writer needed to learn how to use a pen, a 21st Century technical writer needs to know how to use DITA (or another mark-up approach).
It was very interesting to discover that in the field of Web design, a similar argument continues to be made. Web designer Josh Seiden wrote a very insightful article on his blog More Than This, entitled “Designers shouldn’t code” is the wrong answer to the right question. Seiden’s blog post was a response to an argument that “the more you spend on the complexity and details of coding, the less you have to make the product experience better for your users”. He wrote that the core insight (that design should be directed by the customer’s needs, not the tool’s capabilities) is absolutely correct, but that the conclusion (designers shouldn’t code) was wrong. Seiden found the term code problematic. “Do we mean back-end programmers writing APIs in C#? Do we mean full-stack developers writing web applications in Rails? Do we mean front-end developers working in HTML+CSS+Javascript?”. He reported that the “coding ” that most developers are involved with is HTML+CSS+JavaScript, and suggested that is an extension of the toolset designers have been using for 15 years. He went on to point out that Photoshop is a geeky, technical tool, but designers don’t notice that any more because it is entrenched in the workflow.
The conclusion that Seiden reached is that tool competency, be that in Photoshop or HTML+CSS+JavaScript, results in a better product for the customer. For technical communicators, competency in relevant XML applications (our writing tools) results in better documentation. Coding doesn’t come into it.
What do you think?
Use the comments box below to share your thoughts.
I totally agree that a technical writer should know the rules of writing in DITA format, regardless of the authoring tools used. Write structured content has nothing to do with programming languages, what is needed is familiarity with standardized rules of structure and syntax. Just like a good web designer should definitely know HTML, CSS and JavaScript, the author of structured documentation must master DITA-XML.
I agree with the premise of this article and with Enzo as well. I think I disagree with Seiden if he’s saying that “tool competency” wouldn’t mean “coding” in an XML environment. More broadly, I think that a technical writer needs to be not only versed, but (as Enzo says) a master with whatever format they create documentation in. For example, if a writer does (or doesn’t) write in an XML environment, they should or shouldn’t be a master of XML writing. The same is true for technical writers for the web—they should definitely work to master HTML, CSS, and work to be on the forefront by learning HTML5, video creation, etc. If a technical writer only works with MS Word, those specific skills wouldn’t be needed (for present work) but they would want to be a master of formatting, automation, macros, templates/styles, indexes etc.
I have been working with DITA for many years now & I know I’m not using all the potential it offers but can’t imagine life without it anymore. (I wonder when this love affair will die. 🙂 Currently, I can’t imagine working as a technical writer without knowledge of DITA or XML. However, if you’re still working with MS Word I’m not sure you’ll ever need DITA or XML at all. Word 2010 has a wonderful range of templates and the SmartDraw function makes it really easy to create professional output as opposed to earlier releases.
However, if you’re comfortable with both the standard Office applications and DITA, the latter will make your life in terms of controlled writing, versioning, re-use, source control and multiple output production.
I also agree with Fer O’Neill that if you work to produce web-based material you should be decent at web technologies like HTML, Javascript, CSS etc. & you may not even need DITA in that case. We shouldn’t forget that XML alone (or DITA) is not enough. XML can only churn out pretty output if you know how to work with other web-based languages.