TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
eric dunn wanted me to elaborate on the following comment:
> That said, there are some uses for XML within smaller/plain
> projects. TOCs, Index, and Glossaries are a perfect place to use XML
> no matter the size of your project.
and he asks:
How is this "XML" approach different from using tools/features in Word
Well, my original comment was talking specifically about online delivery. I think talking about glossaries will demonstrate my point.
Let's say you are creating a documentation set for a collection of applications (word processor, graphics editor, spread sheet). Typically in a glossary, you'd have a set of terms that would be common to all of these applications, as well as terms that are specific to each application. Using XML, you can tailor the glossary to display the common terms and the terms specific to each application for each of the docs you're creating. All of the terms would be kept in a single glossary.xml file, and would have an attribute (like "type") that would identify a term as either common, word processor, graphics, or spread sheet.
You would then set up XSLs to search the glossary.xml file for all terms with the "common" type attribute and all terms with the appropriate "application" type attribute (word processor, graphics, spread sheet). The output displays just the terms you specify based on the type. You could also direct the output to automatically alphabatize the terms. You could also use the XSL to format the output, font size, color, etc etc. You could even have the xsl point to a css.
You could also add an "id" attribute that provides a unique identification code for each term. You could then use this id throughout your online help to pull the term directly out of the glossary.xml (such as for a definition popup) and display it anywhere, in any way, in any format, at any time.
For further cusomtization, you could create entities that display certain terms/phrases depending on which application you're viewing the glossary for.
A glossary entry might look something like this:
<entry id="field" type="common">
<def>A place for the user to enter information.</def>
The advatage to this is that all of your glossary terms are kept in a single place. Each term is stored in only one place throughout your entire help system: in the glossary.xml file. All links point back to that single glossary term. That way, if you ever have to change a term, the definition is updated throughout your entire system automatically. If you ever have to add a new term, the XSL automatically includes the term and display it in the correct alphabetical order.
Again, XML is not a solution for EVERY documentation project. Like I said before, it can be total overkill for smaller projects. But this is defnitely something that I think will make our jobs easier if we are willing to invest the time up front to set up everything. But once everything is set up, we'll save time producing the finished product.
"And in the morning, I'm makin waffles." ~ Donkey
Sean Hower - tech writer http://hokum.freehomepage.com
NEED TO PUBLISH FRAMEMAKER CONTENT ONLINE? "Mustang" is a NEW single
sourcing tool for FrameMaker that lets you easily publish your content
online. No macro language required! http://www.ehelp.com/techwr-l3
Mercer University's online MS Program in Technical Communication Management:
Preparing leaders of tomorrow's technical communication organizations today.
See www.mercer.edu/mstco or write George Hayhoe at hayhoe_g -at- mercer -dot- edu -dot-
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.