Re: XML & Technical Writers...

[Deborah Ray <debray -at- RAYCOMM -dot- COM>]

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 
documents. 

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-
it-hard-to-develop-usable-pages garbage)...probably
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!
Deborah


>
>Cordially,
>
>
------------------------------º><º------------------------------
>                                 Mary McWilliams Johnson
>                               McJohnson Communications
>                                  Documentation Specialist
>                Web Site Design, Development and Graphics
>                                  www.superconnect.com
>
------------------------------º><º------------------------------
>"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:
>>Hi, Dan,
>>
>>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
>>specific questions.
>>
>>Deborah
>>
>>
>>>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
>>there.
>>
>>>
>>>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.
>>>
>>>Thanks!
>
>>>
>>>
>>
>>**************************************************************
>>* 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.
>>
>>
>
>
>