RE: Why WYSIWYG for XML???

Subject: RE: Why WYSIWYG for XML???
From: Chris Despopoulos <cud -at- telecable -dot- es>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 20 May 2004 09:36:30 -0700


I think I can say I've been officially misunderstood...

Bill Lawrence says:

If the output is one medium, there's no harm in it EXCEPT that you have
yet to separate form from content. For something as simple as a bill,
I'm sure that's fine. It's equally fine if you're doing a one-shot
piece, such as a flyer or an ad. But what if the semantics really
matter throughout? What if you're documenting an API, where every
function, method, class, variable, you-name-it must be marked
appropriately so that one can, from the single source, build
quick-reference cards, context sensitive help, and reference guides? I
would argue that your objections are probably valid given what you're
creating. However, the bulk of us on this list are creating technical
documents, and they are quite different.

Frankly, I don't care if the great masses of writers embrace XML or not,
nor am I suggesting that WYSIWYG tools aren't useful for many writing
tasks. I do care that people doing technical writing begin to think
beyond the mere appearance of the documents they create and concentrate
on the content and the semantics.

First off, there's nothing simple about drafting a bill. If you think so, take a look at the Patriot Act (something every American should have done by now). Here's a link:
http://www.epic.org/privacy/terrorism/hr3162.html

This type of writing makes API documentation look like writing a letter home to mom. The semantics *really* matter throughout, and they have mattered for a long time - for some world-famous gvmts the semantics have mattered since before Christ. Not only that, but the semantics matter so much, the "formatting" of the content is controlled by law. Why? Because the formatting is what expresses the semantics, of course. This is what I mean by tradition. The semantics are already in place, and a large body of people understands the semantics *as they are expressed through formatting*. My point here is that legislation is a perfect example of text that has every reason to be expressed in something like XML.

The "writers" are actually lawers. They have a long history of dealing with these semantics. A significant part of their education revolves around the evolution of these semantics, and their expression via formatting. Now, it would be ideal if these documents could be authored in forms, stored in databases, and plunked either into the forms GUI, or the specific output format du jour. And it would be ideal if all these "writers" would get off their duffs and learn to think of their laws in terms of databases and forms. But there are a number of problems here.

Strom Thurmond, inspite of his position over some aspect of technological development in the US, could hardly have been expected to re-educate himself any time in the last 10 years of his tenure. Nor should we expect Lord Dimplebuttocks to do likewise in Great Britian.

The staff of these honorable legislators include people with similar tenure - somewhere in that staff are people who will be drafting these bills. Again - re-education simply isn't an option because of the cost, and the time that would be lost. If you don't re-educate the old-timers, then you're talking transition. To do that, where all newcomers are required to use the new, forms-based system, you're looking at a transition period of generations. Again, I think that's not practical.

Let's talk about how willing these "writers" should be to re-educate themselves. Their specialties have to do with law, economics, political science, social science, foreign relations, etc. All these fields are rapidly moving targets. Now, on top of their specialties, you want them to devote a very significant amount of their time and energy to re-learning what a legal document should be and how it should be treated. I wonder if you have the time to understand the details of macroeconomics in Africa while you're keeping current in your field? Oh, but in case you're quite exceptional and believe you can do it, I wonder if you believe every Doc Process Architect in the US (or any other world-famous country) is able to do it? Or willing, for that matter?

There is a fantastic amount of written information that is begging to be stored in semantic units. Law, probably all the sciences, and most industry. Have I missed anything? This information *already is* expressed in semantic units. The "writers" are not people who focus on the writing process. They focus on the subject matter. The subject matter is fluid enough that their focus requires full-time attention, which means they will quite naturally *resist* a radically new paradigm. Only if the paradigm truly saves them more time than the effort of learning it - perhaps by a factor of 10 or 100 - will they indulge in the hiatus required to become agile within the new paradigm.

Because of this, I believe it's useful to wrap the new paradigm within the old paradigm to the degree possible. In other words, WYSIWYG is not necessarily bad for XML. Two points here. First, the "wrapping" cannot be perfect - there will be a learning curve for the "writers" inspite of all our best efforts. It falls on us to minimize that curve as much as possible.
Second, the semantics are already there. That means these "writers" are already thinking in semantic chunks. The point is, they use the language of formatting to express the semantics. As anybody who thinks about semantics should know, the language you use influences the way in which you think. Asking these people to change their native language of semantics is asking them to change the way they think - about law, medicine, chemestry, economics, steel production, etc. That may be good. Then again, it may not be so good. Law, especially, is a very subjective realm where the semantics are an effort to lend objectivity. The balance between the two states is something I'm not to willing to tinker with... I'd rather leave that to the experts. Me, I just want to provide a service.

As a parting shot, I'll express my dismay that API documentation has to be composed at all. What I mean is, the source code should simply include extra header files that map their text to the code. For each build, the docs should be automatically generated - proper organization and inclusion/exclusion managed by link statements. Formatting based on semantics, also varies depending on how the code is built. I mean, really... API writers should do no more than edit the programmers' comments. (Just kidding!)



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

SEE THE ALL NEW ROBOHELP X5 IN ACTION: RoboHelp X5 is a giant leap forward
in Help authoring technology, featuring Word 2003 support, Content Management, Multi-Author support, PDF and XML support and much more! http://www.macromedia.com/go/techwrldemo
From a single set of Word documents, create online Help and printed
documentation with ComponentOne Doc-To-Help 7 Professional, a new yearly
subscription service offering free updates and upgrades, support, and more.
http://www.doctohelp.com

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -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.



Follow-Ups:

Previous by Author: RE: Why WYSIWYG for XML???
Next by Author: RE: Why WYSIWYG for XML???
Previous by Thread: RE: Why WYSIWYG for XML???
Next by Thread: RE: Why WYSIWYG for XML???


What this post helpful? Share it with friends and colleagues:


Sponsored Ads