The Advantages of XML in Technical Writing
It's no news that there is demand for technical writers with XML experience, but precisely what might one be expected to know? As a technical writer working with XML, you will be expected to be able to author and publish XML documents. You will also need to become proficient with DTDs and style sheets.
How does XML differ from authoring in Word?
The difference between conventional 'open' authoring (as in MS Word) and markup languages like XML is that the author must specify the 'structure' of each 'element' of the document. In effect, you must explicitly define structural elements such as paragraphs using tags, rather than merely hitting 'Enter' twice. So the 'content' of the document is exactly the same as a corresponding MS Word file - the words and grammar within a paragraph. The only addition for the XML document is that the author must place each content component inside a designated XML 'element'.
The small XML file below shows how a message is contained within XML elements that describe the contents.
What are DTDs?
As a Technical Writer who works with XML, you will have to understand and work with DTDs. A DTD is a description of all the elements that are permitted in any document that you make using that DTD. Two quick analogies: a DTD is 'like' the building code! It is not the plan for your house, or the house itself. It is the set of permissions by which you may include certain 'elements' within a given 'document'. In a novel (usually a rather brief and general DTD) one would expect titles, paragraphs, possibly chapters, but not glossaries, tables of contents, numbered lists and the like. A DTD corresponds to the kind of document a reader or user would expect. A 'message' has a sender, a recipient, a date and content, and seldom more than that, so its DTD is simple. You can make it a lot more complex by adding features like 'title' to 'sender' and then require that all 'internal' messages include the recipient's 'department'.
DTDs define the structural components of a document and because you are required to select one at the outset of your authoring (memo, report, manual, catalogue), all of the features of that document are then available at the appropriate points in the document's structure. The DTD is not a template. It does not necessarily require you to place a paragraph only at one particular location. What it does do is to permit you to use as many paragraphs as you wish at any points in the document where paragraphs are permitted. In this sense it is not a restrictive device except insofar as it does not permit you to use structural features in ways deemed inappropriate by your organization.
What are style sheets?
XML imposes no conditions of 'style' on a document. By not doing so, it permits that document to be displayed in the optimized stylistics of the agent doing the display. In effect, by stating only the structural hierarchy of the document, XML permits it to be 'shown' in whatever form its audience requests - in print as RTF and PDF or in a browser as an HTML web page, using as many multimedia features as have been authored into the document.
The feature that governs the display characteristics of an XML document is called a style sheet. Basically style sheets describe the size and internal relationships of document display, fonts, point sizes - a lot of the features you can set yourself in MS Word. What the style sheet does in addition to how you see the document is to assure that the next user, with a different device and different software, sees a version that incorporates as many of the author's design intentions as that medium can convey. Once again, XML allows for a large range of display features.
Getting started with XML
There is more to XML than just this, but this is a good start. You can learn to read and work with a DTD in your editor fairly quickly, especially if you've been prepping yourself by working with markup in areas like HTML. DTDs require systematic study, some of which you can do online and from texts. You will probably also want some exchanges with others about options and good habits. The Web has a lot of information on style sheets, and if you find yourself facing a particular challenge with a style sheet, you can conduct a web search and you will often find others who have faced the same challenge. If you want to learn how to author in XML, write DTDs, and write style sheets with the guidance of an instructor, you might also consider taking a course such as our Professional XML Authoring course or our Intro to XML Authoring course. Our courses will help you to learn how to work with an XML editor and how to publish XML documents to other document types.
The powerful language features of XML provide consistency and simplicity through standardized document structure definition and style. In the end, it is not enough to simply know the language, you have to use it well.
About the author