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.
Andrew Lakritz makes some excellent points, to which I'd like to
add a couple of my own.
> SGML comes out of the documentation field; it's excellent at
> enabling large corporations to create very large documents, and
> by separating content from format, the content can
> be ported to different publication models easily and quickly.
Don't forget the other SGML promise .... vendor/software
independence! Use the tool you choose, not the one the vendor
locks you into. Failing that, find another vendor.
> XML extends HTML by allowing developers to design their own tags.
Not strictly true. If you suppose that HTML is built upon SGML,
take away the SGML and replace it with XML. You can then
replace HTML with XHTML, but also add in WML, VoXML, MathML,
EdaXML, TML, QML, whatever ML you want.
> .. and most browsers I know of don't parse XML directly.
The msxml parser is incorporated inside Internet Explorer 5.
Originally, all XML was parsed and badly formed XML was not
displayed. On second thought, they realized that forcing web page
authors to write well formed XML, in an environment of HTML where
almost anything goes, was probably going to be a major obstacle
to the acceptance of XML. Automatic parsing was subsequently
disabled and to force parsing now you need to use scripting code.
> You need to have an XSL file to convert the XML to HTML
> display format.
Not necessarily. Internet Explorer has a built-in XSL stylesheet,
though it doesn't give you much. However, DSSSL is still a serious
(though neglected and poorly understood) alternative ... you still
can't do multiple columns, right-to-left text flows, and all sorts of
other things with XSL.
> I am quite sure that soon we'll see technical documentation using XML
> as a primary mode of delivery, even though it was not intended for
> that use. But XML is best at communicating very rapidly changing data
> (like stock quotes, bank balances, foreign exchange rates, commodity
> prices, sports scores, products and service descriptions and details,
> etc.). If the stuff you are documenting changes in a way that needs
> documenting only twice or four times a year, perhaps XML isn't the
> vehicle of choice?
OK, having been destructive so far, let me now be constructive. A
lot of what many of us try to document is software; user interfaces.
These things require rapidly changing documentation -- we call it
> My current problem to solve is how to embed documentation in the
> source in such a way that when the source changes (a code module, a
> database stored procedure, a database table, etc.) one can
> automatically update the documentation.
XML offers the opportunity to embed the documentation into the
software (aka source) in such a way that the information you
deliver can be completely dependent on the context.
> I don't think XML is the answer to that problem necessarily;
> automation is the answer, and a lot of work creating a useable
> documentation format. And a lot of documentation
> effort itself.
XML isn't a solution in itself, it's one step along a path to a
thousand solutions. It's an enabling technology that makes other
> But so far I have not solved the problem, at least not
> in my current work context.
Some of us are lucky to be working on the solutions!
Changing topic slightly, there is another area in which we as
technical communicators will start to reap the benefits: structured
vector graphics. VML (Microsoft's Vector Markup Language) has
been around since Internet Explorer 4. Though largely ignored, you
could do some pretty neat things with it (such as interactive
graphic objects, but years before Flash came along). SVG
(structured vector graphics) is the XML application that replaces
VML. There is a plugin for Netscape to display SVG (see the
Adobe site) and SVG creation tools are appearing slowly. Adobe
are putting a lot of time and money into developing SVG support
and I think it will become a realistic graphics format within the next
2 years. So, given SVG ... imagine interactive graphics containing
objects that can be manipulated, hyperlinked, keyed to text, and
scale perfectly to any resolution. If nothing else, it will take a lot of
the drudgery out of parts lists, but it opens up all sorts of
interesting new possibilities for integrating text and graphics in
SVG is, however, just one application and is very much the tip of
the proverbial iceberg. There are all sorts of other initiatives and
applications that may or may not revolutionize our craft. Things
such as topic maps, SMIL, OpenMath, and many, many more.
This is just the bginning ...
*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com
Sponsored by Cub Lea, specialist in low-cost outsourced development
and documentation. Overload and time-sensitive jobs at exceptional
rates. Unique free gifts for all visitors to http://www.cublea.com
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.