Re: XML & Technical Writers...

[Mary McWilliams Johnson <mary -at- SUPERCONNECT -dot- COM>]

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

I really appreciate your taking the time to spell all this out for me and
the other "listees."

Cordially, Mary

==============

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