Yes, a real value, Was Real Value?

["Tim Altom" <taltom -at- simplywritten -dot- com>]

Good grief. Not again.

Andrew, I've been where you are. And you haven't been where I am. I am
therefore qualified to speak about both worlds. And you are constructing a
straw man.

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.

The documents you produce as a "freewheeling independent" are inherently
flawed, too. They're hard to maintain and almost impossible to reuse in
pieces. They may or may not be interesting, but that's purely subjective,
impossible to measure. They are useless if the document must serve more than
one purpose. Basically, the documents you describe are dead ends, impossible
to quickly and easily reuse. This drastically increases the eventual cost of
the documentation, but of course by then the "freewheeling independent" is
long since down the road, happily banking the client's money. It's only
after owning the dead end documentation for a while that the formerly naive
client realizes that he's bought a one-shot. He may be a manufacturer or
software house, but in any case he's always alert for ways to reuse code,
parts, or ideas...except in the documentation. There he's just bought
himself a one-trick pony, having traded off some up-front sober planning for
illusory speed.

You also ignore the fact that structured documentation can be done with the
simplest of tools and still fulfill its function. I recently completed a
lengthy set of manuals for a local company installing a new enterprise
software system. I could throw in the help files FOR FREE because I used a
structured approach. And it was done in Microsoft Word. Our company won the
contract because we were highly competitive over "freewheeling independents"
who couldn't provide the client with precise time and budget estimates, nor
with free help files. Our structured approach enabled us to actually come in
under budget and well within deadline, even with numerous changes. The
client was thrilled, as most clients are when they're given something
predictable in the midst of a frenzied project. We could even supply the
client with a "shell" help file to experiment with before we'd written a
word!

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. It permits easy coordination of multiple writers, because there is
no misfit between them. It improves the coordination with contractors, too.
Finally, it enormously simplifies budgeting, estimates, and the like. It is
predictable, therefore efficient. And it doesn't have to be bloated and
top-heavy in small applications. We can teach a fully-formed, existing
structured approach in three days, fully usable in small shops. In today's
market, where you can't find good, experienced people, and even if you could
the budget won't cover them, a structured approach lets a writer do more
work without exerting more effort, and her manager has an easier time, as do
the editors, proofreaders, and anyone who has to interface with the tech
pubs dept. A small department could move to a basic structured approach for
about $20,000 or even less, with ROI within 12-18 months.

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. With only what they want. Users don't want
manuals that are interesting...they want manuals that work. And work their
way. They don't need manuals to be "Dummies" books. When they consult the
manual, they're under the gun, on the job, maybe in a muddy field in the
rain or up against a deadline with the boss yelling down the hall. To hell
with interesting. They need a way out of an impasse, and they need it now.
Structured documents can be reassembled in different ways, as if the
documentation were a database of user information, giving users instant
access to only what they need, without plowing through the "interesting"
stuff. Small systems can be designed to scale up to this over time, by the
way.

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.

Tim Altom
Simply Written, Inc.
Featuring FrameMaker and the Clustar(TM) System
"Better communication is a service to mankind."
317.562.9298
Check our Web site for the upcoming Clustar class info
http://www.simplywritten.com

----- Original Message -----
From: Andrew Plato <intrepid_es -at- yahoo -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Sent: Monday, November 27, 2000 3:10 PM
Subject: Real Value??


> Another round on the old "structured" vs "not structured"
>
> Let's get rid of all the "my tool is bigger than your tool" arguments and
look
> at the core issues to this never ending debate of structured documentation
> systems.
>



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY.
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Sponsored by SOLUTIONS, Conferences and Seminars for Communicators 
Publications Management Clinic, TECH*COMM 2001 Conference, and more 
http://www.SolutionsEvents.com 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 
http://www.raycomm.com/techwhirl/ for more resources and info.