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

Subject: Re: TECHWR-L: XML & the future of tech writing (topic from last week) LONG
From: Katie Kearns <kkearns -at- cisco -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 31 Oct 2001 10:03:58 -0800

At 12:30 AM 10/31/2001 -0800, you wrote:

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

I'd agree. It's silly to say everyone should do anything.

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 think Frame does -- or if not Frame, than Frame + SGML. There are better tools, though. I don't think Frame does a lot of work helping you validate your XML or doing anything particularly interesting or helpful.

Promises of better efficiency? Isn't accuracy more
important than efficiency when it comes to technical information?

Sure -- and XML doesn't hurt accuracy, does it?

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!

Actually, in some cases, relational databases are totally incorrect tools to use for XML. Other times they're perfect. It all depends on your XML docs, how structured they are and a million other things. XML-dev recently had a very lovely discussion about it, and some of the information is summarized here:

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.

Why? If you implemented an XML system, why would writers necessarily need to know anything about it? If you set up some good processes (oh, I know you love those), it wouldn't be necessary at all. One guy or a small team could create the system, and everyone else would follow it. That's the beauty of processes. Everyone can go do their work and not worry about learning XQL or anything other Great New Thing that someone tells them is going to be so wonderful.

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.

It has nothing to do with writers or programmers -- it has to do with finding the right tools for the job. If another system happens to offer you some great happy features that makes life worth living, maybe you should use that one instead.

I don't advocate running off and using whatever new thing comes down the line, but the way you cling to the lack of change just reminds me of all of those people you attempt to ridicule because they refuse to use any other tool than FrameMaker. Look outside your little box every once in a while. ;)

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.

There's a difference -- volume. If you have 1000 writers all writing documentation constantly, it's a lot more data to present on a web page than some web developer who is trying to put three news stories on the company intranet. :P

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?

So, all you're saying is you think moving to a bad XML system is a bad idea. Well, crap. Of course it is. Moving to a bad anything system is a bad idea.

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.

What if the point isn't that you want to "save the writers from the evil content" but that you want to make it easier to produce multiple forms of documentation from one batch of work? I know tons of people will disagree about the world of single-sourcing, but frankly, I think it works.

So -- if your goal in life is to write a doc and have it turn into content on your web page that people can easily find, turn into a book you send with the product, turn into online help as part of the product, and pull out relevant bits and make a quickstart guide or something all so you don't have to re-write tons of crap... that's what separating content from format is all about. All the same content (more or less -- surely you would only put a subset of information from a user guide in a quick reference) but in a bunch of different, easily-produced formats.

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.

Sounds like they spent too much money teaching the writers crap and had a crappy system. ;) I mean, in a large company, there's no reason for all of the writers to even be FrameMaker wizards -- get people who are and get them to make some templates and tell everyone else to use them.

Just like my engineers don't all know how to merge their branches in clear case or source safe or whatever they use -- they have a few guys who do it. Not everyone. That's just a big waste of time.

All my developers don't know all of the coding languages we use. One guy may know Java and perl, and another one knows javascript and HTML. Whatever. Why should they know everything as long as everyone else does their job?

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.

Yep. It all depends on your needs. No one-size-fits-all.

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

Wait... who are you? You don't sound like 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

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 for more resources and info.


Re: TECHWR-L: XML & the future of tech writing (topic from last week) LONG: From: Andrew Plato

Previous by Author: RE: TECHWR-L: XML as Help Format
Next by Author: Re: the "word" dealing, not to mention cope
Previous by Thread: Subordinated bookmarks in PDF using Frame
Next by Thread: Re: TECHWR-L: XML & the future of tech writing (topic from last week) LONG

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

Sponsored Ads