RE: TECHWR-L: XML & the future of tech writing (topic from last week) LONG

["Pete Sanborn" <psanborn2 -at- earthlink -dot- net>]

> In many respects I agree with both Andrew and Chris but, by the same
token,
> I'm in disagreement with probably everyone on this thread. Tools are not
the
> job, developing comprehensible documentation is. The tools are just a
means
> of helping us develop the docs. Computers have made us faster and provided
a
> lot more options for producing docs but, as Andrew points out, they
haven't
> made us better or smarter writers. If we can't convey comprehensible
> information, no tool is going to make the documentation any better. Tools
> are for OUR convenience, not our target audience.
>
> It is ironic that this debate is still ongoing because I had this same
> discussion about 10 years ago. We are supposed to be about producing docs
> that help people perform tasks, understand systems and services and
explain
> how to use equipment. A tool, no matter whether it is XML or an IBM
> Selectric, doesn't produce a document that is more useful to our target
> audience if we, the document developers, haven't a clue what the heck
we're
> talking about. Colleges with Tech Writer programs still, for the most
part,
> focus on the journalistic aspect of writing, but that doesn't produce
better
> tech writers. Someone with great style can write really good,
grammatically
> correct gibberish that benefits no one if he/she hasn't bothered to find
out
> their product does or how it works.
>
> Tools like XML, HTML, etc., that allow us to develop documents for the web
> are great - as long as we have functioning computers and electricity.
Let's
> take a moment and consider the potential for the release of a huge
> electro-magnetic pulse that wipes out all of our computers (such as is the
> premise for the TV show Dark Angel). What good will all these tools be if
no
> one can get to the documentation because their computer has gone to
> cyber-heaven? While the example, here, may be predicated on a TV show, it
is
> an entirely plausible scenario, particularly in light of today's global
> situation.
>
> These discussions of tools, etc., are certainly interesting, but they take
> our focus away from the primary issues that affect us as documentation
> professionals. IMO, those issues are 1) understanding the product, service
> or technology we are documenting, 2) understanding our target audience and
> their documentation needs, 3) understanding how documentation is used by
the
> target audience and the environment in which it is used, 4) understanding
> that, in the high-tech world at least, a significant number of our target
> audience are not from English-speaking countries, so a lot of our golden
> prose is wasted, 5) understanding that we are facing an illiteracy rate
that
> is approaching 40% and a functional illiteracy rate that is approaching
50 -
> 60%. These are things that materially affect us as a profession and are of
> greater significance, IMO, than the focus we have today on which tool does
> what better for web docs that may be totally useless next year or even
next
> month.
>
> If we want to ensure that we have a profession to talk about 25 years
hence,
> it might behoove us to maintain our focus on the big picture and worry
less
> about who knows what about which tool. If we can't convey complex
> information in a way that others can understand it, we may well find
> ourselves being replaced by Admins who can.
>
> Regards,
> Pete Sanborn
>
-----Original Message-----
From: bounce-techwr-l-81537 -at- lists -dot- raycomm -dot- com
[mailto:bounce-techwr-l-81537 -at- lists -dot- raycomm -dot- com]On Behalf Of Andrew
Plato
Sent: Wednesday, October 31, 2001 3:30 AM
To: TECHWR-L
Cc: cknight -at- attcanada -dot- ca
Subject: Re: TECHWR-L: XML & the future of tech writing (topic from last
week) LONG


"Chris Knight" wrote...

> It is precisely to users of these tools that I am talking. Mr. Plato
> seems to think I am advocating some nerdy "advanced" tool.; not so.

No - I think the tool set for XML is too wide and disparate right now to
warrant blanket statements like "all tech writers should use XML."  That's
the same as me saying "all tech writers will be using Word in the coming
years."

> I am talking about working tech writers working with the available
> tools, but realizing that there are strong forces at work pushing us
> toward tools that read and write XML. I believe that as users of these
> tools we should in turn push the tool vendors (especially Microsoft and
> Adobe) toward achieving this end.

Word 2000 and XP already can output XML. Its one of many formats it
supports. I don't believe Frame does - but its been a while since I have
used Frame.

> I am talking about organizations which produce large amounts of
> documents, and consequently employ large numbers of us to produce those
> documents. Such organizations want both increased productivity AND
> increased flexibility out of publications groups, and they want to do it

> while increasing the control they have over the content of those
> publications. (I include here any form of delivery--print, help,
> online). Thus the mantra of "single sourcing".

Companies that produce large numbers of documents and employ large numbers
of tech writers and have large budgets generally need larger, more
efficient methods to produce documents. I am sure that XML is one option.
So is Word with an established style guide and a well run organization.
Both will do the job - produce docs. There may be more manual procedures
here and there - but if that is working for an organization, what's the
incentive to change? Promises of better efficiency? Isn't accuracy more
important than efficiency when it comes to technical information?

> It won't just be word processing tools that will use XML as document
> storage: most XML in fact will actually be created and maintained by
> database systems. Work is ongoing to interface XML with SQL (Structured
> Query Language); one implementation wending its way through the
standards
> mill is called XQL.

Here is another example of a solution to a problem that doesn't exist. SQL
is a perfect good way to get stuff out of databases. But, of course
somebody decides - SQL isn't good enough - we need XQL!  A format that
will only work with XQLPro - the half/designed, semi-tested, obsessively
bizarre tool from the same people who developed this standard. Who now
demand that Word and Frame use XQL - because SQL wasn't good enough. So
now, I have to send all the writers to XQL classes after I just blew
$9282029 on XML classes - when the whole lot of them still haven't written
one damn thing.

Now, you could set up a Oracle or SQL Server database, code some basic
stored procedures, and build a front-end for them using a whole wide array
of tools out there - including Visual Basic. All tried and true
technologies - that would do the same, exact thing as some exotic XML
based solution. However, since VB and SQL Server are perceived as
"programmer tools" writers avoid them like the plague and fall in love
with some XML thing which has a much higher buzz-to-bullshit ratio at this
year's STC conference.

Actually - you know what - you can actually single source using *gasp*
Word and Access! I've done it. Works like a charm. Store all the data in
Access tables and use mail-merge to put the data into the Word doc. Of
course, that's not nearly as fun as attending XML seminars - but it got us
paid.

> This is how "single sourcing" will be implemented: we'll store the
> document *content* in one place, as a database implemented in XML, and
> store document *structure* elsewhere (also in XML). Document *format*
> will be stored in the stylesheet.

This reminds me of the "database push" that happened in web development
about 3 years ago. You were nobody unless you had a database-driven web
site. Now here we are, 3 years later and a lot of sites are abandoning
costly database-driven sites in favor of good-old HTML pages and a
semi-intelligent web master. Proving once and again, the more you overtake
the plumbing the easier it is to stop up the pipes. Just because its
faster and more powerful doesn't mean its better. Jaguars are fast and
powerful - and junk.


> As a result, in some ways writers' tasks will become easier. However,
> anyone who has difficulty separating content from structure and format
> will have to relearn how they write. This could be a major change for
> many of us. In my judgment, it will make us better writers.

I wholly disagree. It makes people worse writers.

Why? The biggest problem among tech writers today isn't that they can't
produce documentation faster - its that they have no clue what they are
documenting. You can put a toad in a Porsche, but he won't know where to
go. Likewise, you can put a ignorant tech writer in a huge XML environment
and it won't matter if he doesn't know what to write.

The last thing we need is to force people to work under even MORE
abstracted and uninvolved conditions. Most organizations can't even manage
to tell the tech writers about system changes - how on earth is separating
the content from the format going to improve this situation?

Just recently, we had a techw-l post where the management was enlisting
the help of secretaries to finish off documents. These people are not
going to handle some esoteric, exotic XML land where everything is nicely
chunked and organized into tasty bite sized morsels.

Moreover, this who "abstract the content from the format" issue can be
easily solved by hiring skilled, intelligent people who are willing to
learn the content, conform to a style guide, and remain organized.

XML is not a panacea. Its just a new way to turn the same crank. I have
been listening for over a decade to people drone on about how structured
systems this and XML that - you know what? Docs STILL SUCK! I have a
client - big complex structured authoring system...they threw the whole
thing away. You know why? After spending hundreds of thousands of dollars
on consultants, software, and development - they still couldn't write
decent documentation. You know why? All their writers were expert database
engineers and FrameMaker wizards - but they didn't know SQUAT about the
technologies they were supposed to be documenting. They had a very
efficient method of producing crap.

> I'm just engaging in (informed, I think) crystal ball gazing folks. Will
> this happen all at once? No. Will *everybody* decide to use XML?
Certainly
> not--as I said, this will probably only be adopted in large or
particularly
> security-conscious environments.

Security-conscious environments don't need XML. They need better firewalls
and intrusion detection system. XML files are just as easily cracked open
as any other file, so there is no benefit there.

What will happen is that XML along with existing technologies will become
one option among many. Some organizations will adopt it and have great
success. Some won't. Many, will stick with their existing infrastructure
because it works.

Chris, I don't think you're wrong. I just think you're looking at this
from a very cloudy crystal ball. I am sure in your environment, at your
firm, XML has worked. Your firm has also had somebody, namely you, who is
obviously very committed to this technology. Just because it works for you
doesn't mean it will work universally.

One of the first things you learn when you start doing consulting is the
realization that no two clients are alike. What works one place won't work
in other places. Hence the fatal flaw many consultants make - they assume
one trick can work everywhere. They are a hammer, all problems are nails.

So while XML and systems like it are cool. Lets remember that it is one
option among many. And it won't solve all problems...and it may introduce
many others. Just as working with Word can solve - and create problems.

Andrew Plato


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Announcing new options for IPCC 01, October 24-27 in Santa Fe,
New Mexico: attend the entire event or select a single day.  
For details and online registration, visit http://ieeepcs.org/2001

  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

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