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.
Subject:Re: XML & Technical Writers... From:Mary McWilliams Johnson <mary -at- SUPERCONNECT -dot- COM> Date:Tue, 14 Apr 1998 18:04:04 -0500
Thanks, Deborah, that's probably the most helpful explanation of XML I've
seen yet. I guess it's something to look forward to, but I won't be holding
my breath awaiting it's full implementation on Web pages.
For now, I have little use for anything that only a handful of viewers can
I really appreciate your taking the time to spell all this out for me and
the other "listees."
At 01:49 PM 4/14/98 -0600, Deborah Ray wrote:
>At 02:02 PM 4/14/98 -0500, you wrote:
>> Everything I read says you can make up your own
>>tags. How does this work out in practice?
>>From what we've seen, making up your own tags offers lots
>of potential. In particular, rather than being bound to
>the tags that, say, HTML offers, you can use ones that
>meet your document needs. The result is that you can
>specify the context for each piece of information on the
>page, which helps you in developing multiple or large
>The drawback, however, is that the "making up your own
>tags" aspect usually includes developing a DTD (Document Type
>Definition). It's easy enough to, for example, make up a
>tag called <CAPTION>, which you might use to mark figure
>captions. The tricky part is that you have to further
>define the tag--where in the document it can go
>(only above figures? only below?, where ever needed?),
>how many times a caption can exist (at least once? only once?
>etc.), and so on.
>This sounds complicated, I know, but, to answer your question
>of how this works out in practice--it's not as complicated
>as it sounds. In fact, in planning documents, we end up
>determining most of these aspects anyway. Using XML, you just codify
>your document plan. Additionally, developing a DTD forces
>you to put a lot of thought into the document structure, which
>is a good thing, right?!
>Also, you don't absolutely have to develop a DTD to use
>XML--for more extensive uses, you'd want to, but for smaller
>projects (or even projects that require extensive planning
>and you need several iterations to get the structure just
>right), you don't have to develop the DTD.
>How will I know if the browsers
>>can understand my code?
>Browser technology isn't quite up to speed yet--in other
>words Netscape and Microsoft are frantically working to
>support XML in the next browser versions. So, as with other
>cutting-edge Web technologies, you'll have to wait a bit
>before its widely supported. Currently, Microsoft offers
>a technology that lets you view XML data in Web pages, but
>only through Internet Explorer 4.0. It doesn't support viewing
>pure XML documents, but it's a start.
>If you're wondering about whether browsers will end up
>offering competing XML extensions (or some other makes-
>not. Because XML is completely customizable, you (not
>the browser companies) are in charge of what features
>are available. You provide the XML document; you provide
>the DTD (rules); you provide the style sheet (for formatting
>info). The browser, then, just assembles all the pieces
>for you or your readers.
>Hope this helps!
>> Mary McWilliams Johnson
>> McJohnson Communications
>> Documentation Specialist
>> Web Site Design, Development and Graphics
>>"One must learn by doing the thing; for though you think you know it,
>> you have no certainty until you try."
>> --Sophocles, c 496-406 B.C
>>At 12:44 PM 4/14/98 -0600, Deborah Ray wrote:
>>>You've hit on a topic that should prove worthwhile to tech writers
>>>in the very near future. Following is a (VERY brief and cryptic!)
>>>rundown of what XML offers tech writers.
>>>In addition to the data definition and exchange stuff that
>>>you mentioned, XML
>>>* Combines SGML's power and scope with HTML's ease of use,
>>> giving you the best of both technologies. You can think of
>>> XML as being "SGML-lite" or "HTML on steroids."
>>>* Makes reusing information relatively easy and inexpensive--that is,
>>> you can develop information to include in a product's documentation
>>> and easily reuse it for training materials, product descriptions,
>>> or whatever. You don't have to deal with recreating information,
>>> changing formats, or addressing platform compatibility issues.
>>>* Lets you create documents that meet very specific needs--
>>> you create your own document structure and rules as well
>>> as your own tags and attributes.
>>>* Can help you develop consistent document sets. XML not only
>>> lets you organize documents and information very precisely, but
>>> it also can force developers to comply with the structure
>>> and organization outlined in the DTD you create.
>>>* Is great for creating large document sets, especially ones that
>>> are developed by teams of people or developed over months or years.
>>> As mentioned above, XML can force compliance with the DTD (so even
>>> long, drawn-out projects can include consistent documents), and
>>> it's text-based, meaning that the information will be readily
>>> transferrable in the long term.
>>>* Lets you identify contexts for words on the page--that is,
>>> this is a figure caption, this is a figure reference, etc.
>>> Because you create your own tags and attributes (and are not forced
>>> to use ones that the W3C specifies), you can specify exactly how
>>> words are used.
>>>* Lets you address a potentially large audience using a
>>> variety of platforms. As XML tools and technologies develop,
>>> XML should help eliminate cross-platform, cross-software,
>>> and browser-specific issues.
>>>At this point, all signs indicate that XML offers the potential
>>>of being an ideal tool for tech writers to learn and use. In fact,
>>>tech writers are ideal candidates for using this technology because
>>>we already have the information development, design, and presentation
>>>skills necessary to develop these structured document formats.
>>>Of course, all of XML's great potential for tech writers is just that--
>>>potential. XML is still very new, and currently you won't find
>>>many tools to develop or browse XML documents.
>>>BTW (as I think Eric mentioned to you off line?), we are currently
>>>working on an XML book, and we have just recently completed an
>>>article on what XML offers tech writers--apparently a timely topic!
>>>Hope this brief summary helps, and feel free to holler with
>>>>I am attempting to do some research, in the form of in-person interviewing,
>>>>on the subject of XML and its impact on technical writing. So far, while
>>>>there is a lot out there about XML, I have found little about how technical
>>>>writers might use it, or the possibilities it may open up in the field. XML
>>>>seems to be targeted more towards business and information exhange, and
>>>>less toward content creation, which may explain why there is little out
>>>>Does anyone have any ideas about it this or leads to an interview?
>>>>I am in the San Francisco Bay Area, but would be willing to interview via
>>>>email, if necessary.
>>>* Deborah S. Ray, debray -at- raycomm -dot- com, http://www.raycomm.com/
>>>* co-author _Mastering HTML 4.0_, _HTML 4 for Dummies Quick
>>> Reference_, _The AltaVista Search Revolution_, and others.
>>>* RayComm, Inc., currently accepting contract inquiries.