| |
The advantages of XML in technical writing
There are some web sites you just want to take home and cuddle!
Try http://www.technicalwriter.computerjobs.com if you've ever thought
about being a technical writer. I was a bit surprised by the numbers:
Tech Writer average salary (US) at $42 thousand -- not bad. Tech
Writer with XML, add an extra $19k! It's no news that there is demand
for writers with XML experience but precisely what might one be
expected to know and to do for that 43% jump in one's pay. A brief
review of expectations is in order. For this money you will be expected
to be able to develop XML documents, some of which can be remarkably
complex, but all of which are remarkably consistent -- that's one
of the big strengths of XML -- consistency.
The difference between conventional 'open' authoring (as in MS Word)
and all markup exercises (including XML and its parent SGML) 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' and so on...
As an XML Technical Writer you will also 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 'memo' has
a sender, a recipient, a date and a subject 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' memos 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
(No before in our books!). Because a particular
DTD permits you to use numbered lists in all paragraphs, you may
use as many paragraphs as you wish in the document and as many lists
within any of them. The DTD is not a template. It does not require
you to place a paragraph at any 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, by professional groups and by general observation
of standards. "Please no glossaries in titles, or sections inside
lists!"
DTDs with specific structural features exist for shared kinds of
notation. TEIS is a large DTD set to facilitate the shared development
and exchange of academic data, to enable scholars to build consistent
documents which can be included in larger compilations - articles
in Proceedings, chapters in texts, etc. Here the use of such DTDs
assures that your work can be immediately assimilated in a larger
bank of information using the same 'Document Type Definition'.
Do you see how it's like the Building Code - we all use the same
'standards' to wire electrical sockets in all our houses, but the
'electrical standards' do not tell us how many sockets we may have,
or where they must be placed. DTDs are not templates. In my metaphor
a template would be the plan for the house, not the standards for
housing construction.
Now let's go to style sheets. XML, like SGML, imposes no conditions
of 'style' on a document. By no doing so, it permits that document
to be displayed in the optimized stylistics of the agent doing the
display. (Got that?) 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 a display
in a browser, 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.
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, but you can
do a lot on your own. In the matter of style sheets, the Web has
a lot of information. Soon style sheet features will become increasingly
more common in editors, so learning to use them will be much easier.
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.
Dr. Paul Beam is a professor in the English Department at the University
of Waterloo, where he instructs and does research in online learning
and technical writing. He is working with other principals of Online-Learning.com
to provide courses in technical subjects and to develop custom online
courses for commercial companies.
© 2000 Online-learning.com
|
