Re: Yes, a real value, Was Real Value?

Subject: Re: Yes, a real value, Was Real Value?
From: Andrew Plato <intrepid_es -at- yahoo -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 27 Nov 2000 14:00:26 -0800 (PST)

--- Tim Altom <taltom -at- simplywritten -dot- com> wrote:

> Structured documentation involves tradeoffs. So does everything else in
> life. Every engineer can sorrowfully attest to the fact that all designs are
> actually bundles of tradeoffs.

Yes. And structured documentation systems have some HUGE tradeoffs. One of them
is that they CANNOT under any circumstances make people better writers. They
merely can help organize stuff.

If organization is a problem for documents, then structured documentation
systems are ONE of many solutions.

But, I'm sorry, Tim. Structured documentation systems are not a panacea to
solve bad documents. In many cases, these systems merely organize bad content
giving it false credibility.

> The documents you produce as a "freewheeling independent" are inherently
> flawed, too. They're hard to maintain and almost impossible to reuse in
> pieces.

ALL documents have inherent flaws. You said, all things are a matter of
tradeoffs. Your solutions have just as many bad aspects as the "freewheeling"

I contend that when you're dealing with detailed documents about complex
technologies - you need a freewheeling writer who can handle the technical
issues first. How he/she physically generates that documentation is irrelevant
as long as it gets the message communicated properly.

> Further, a structured approach drastically shortens training time for newly
> hired writers. It enables newbies right out of school to get up to speed
> quickly.

But it does not make them better writers. The ability to tweak and fiddle with
DTD tools is insignificant if the documentation those tools produce are dumb,
inaccurate, or misguided. A brain still must command the tools.

Newbie writers would be MUCH better served to "learn it the long way." What I
see these days are an entire generation of writers getting pumped out of
companies and schools with ZERO technical skills and an over reliance on
proprietary tools.

There is a reason you don't get a calculator in third grade math.

> It is predictable, therefore efficient.

Oh, if I had a $1.00 for everytime a consultant used this line.

Predictability DOES NOT equal efficient.


Efficient DOES NOT equal quality.

Lots of companies are efficient at producing crap. Look at GM. Ever driven a
Chevy Cavalier? Efficient crap.

> And what do users get? More. Lots more. More information, more choices. They
> don't have to be locked into the paradigm a dead end document writer assumes
> they want. In a truly structured environment, users can demand manuals done
> like Burger King...their way.

As long as their way conforms to the pre-chewed templates, structures, and
chunks that are stored in the documentation system. What if that chunk doesn't

> Tell you what; in the next couple of weeks I can write up a case study of
> the single source project I mentioned in this message. If anybody wants it,
> I'll gladly email it to them. I can't release the documents themselves due
> to nondisclosure agreements. I'll let my colleagues judge whether or not a
> single source project is worthless in small projects.

Personally, I think you should move your thinly disguised marketing efforts off

Of course you're going to show that your solution has ROI. That is like asking
George W. Bush to count the Florida ballots. Gee, who do ya think would win?

Here's a challenge for you, Tim. Show us how your system can benefit these

1) Technical Accuracy
2) Readability
3) Writer's technical expertise
4) Style (how can it make documents more interesting).

Forget the money and how its all more efficient. Show me how spending hundreds
of thousands of dollars on a large documentation system will improve these core
issues of quality technical documentation.

Andrew Plato

Do You Yahoo!?
Yahoo! Shopping - Thousands of Stores. Millions of Products.

Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY. or 800-646-9989.

Sponsored by SOLUTIONS, Conferences and Seminars for Communicators
Publications Management Clinic, TECH*COMM 2001 Conference, and more or 800-448-4230

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.

Previous by Author: Re: Managing Engineers (long)
Next by Author: Re: Real Value??
Previous by Thread: Yes, a real value, Was Real Value?
Next by Thread: RE: Yes, a real value, Was Real Value?

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

Sponsored Ads

Sponsored Ads