TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
--- Dan Emory <danemory -at- primenet -dot- com> wrote:
> The arguments I responded to were those relating to his comments
> about structure, not process. In those comments, he did frame
> his arguments in either-or terms.
Okay, I'll admit my zeal overcomes me and I am prone to exaggeration. I won't
disagree that I hit "processism" pretty hard.
However, I don't see this as an either-or debate. I see this, as Bruce pointed
out, a question of focus or emphasis. The values and priorities people place on
certain tasks says a lot about how they work.
For example, people who consider human interaction paramount to intellectual
challenge make better sales people. People who consider perfection paramount to
production make better scientists. How we behave and what emphasis we place on
our job duties, I think, explain how we work.
I think people who place process and procedure above content and usability have
the wrong focus for technical documentation. Maybe these people make great
business consultants and systems analysts. But as technical writers, I don't
believe an emphasis on process is the best way to work.
> Furthermore, I am not an advocate of blind process. I understand
> fully where that leads. But Andrew seems to argue that there is
> no alternative. I believe there is. I call it organic design, which
> combines structure and process in an integrated whole.
Okay, we're closing in on common ground Don. You're wrong that I don't think
there is an alternative. There is. My alternative stresses the following:
In other words, a good document is first a foremost technically accurate (a
content issue).
Second it is targeted properly to its audience (another content issue in my
mind).
Third it is "accountable", in that the writer has a clear path to validity on
the information. Ideally, that path traces to an SME and is backed up with the
writer's own knowledge.
Fourth, the document is well organized. Again, this is a content issue to me.
The organization should always flow from the content. Or in other words, the
content should drive the organization.
Fifth is design. A good document must use a design motif that is recognizable
and accessible to the reader.
Last, is marketing. A good document effectively "markets" its designs,
products, etc. by connecting them to the real world. It demonstrates the value
of the information and why readers will benefit from knowing what is in the
manual.
My alternative is not a rigid, unflappable XML implementation. XML is merely a
tool to be exploited. When it comes to a document, it really should not matter
what tool is used. Yes, some tools are better for some jobs, but that is the
daily mechanics of the job. If the tool hinders any one of the items I
mentioned, then to tool isn't helpful.
Unfortunately, many tools do get in the way because the divert the writer's
energies from ensuring accuracy to forcing a square peg into a round hole. The
writer is directing so much energy to categorizing and cataloging the chunkets
of information that context and flow are lost.
What happens in a lot of XML solutions is a loss of conceptual integrity. You
have all these chunks of information that are so genericized that there is no
overriding conceptual vision to the work. The work becomes so generalized and
dry that conceptual inner-connections in the document are lost in order to
support the rigid hierarchy of the system.
When I read a manual, I want to see themes established and played out. Many
overly structured systems do not provide a way for a writer to implement themes
and "global" conceptual constants (or as I call them 'mem classes').
> But the problem with Falling Water (it's now falling down as Andrew
> pointed out, but the problem is being fixed now) was actually a failure
> of process. The structural engineer on Wright's staff failed to consider
> the negative moment of force on the cantilevers. Implementation
> of the appropriate checking process as the design evolved would
> have caught that oversight. The same goes for the notorious fact
> that the roofs leak in many of Wright's homes. A better process
> would probably have found a way to avoid that problem too. The
> inclusion of those process steps would not have interfered with
> Wright's creativity, they would have enhanced it.
Wright was a designer not an engineer. The problem with Wrights work is simple
- his designs were too advanced for the materials of the time. I hardly doubt
some huge process checking measure could have overcome this at the time.
In reality, the content of Wright's homes (the bricks, mortar, steel, etc.)
were not up to par on his designs. He had exquisite designs, poor
implementation. Which proves my point - the most exquisite designs fall to crap
if the implementation isn't good.
> Then your students were in a developmentally frozen state.
> Of course as we gain experience we don't follow the original
> drill, whose purpose was to instill the concept, not to prescribe
> a permanent method.
So as writer's get more knowledgeable they can cast off the processes and just
write. I'm with you here Don, but I don't think you realize what you just
said...
> We all evolve our own ways of conceptualizing
> structure in actual practice. As a matter of fact, I've found that
> authoring structured documents (e.g., SGML) that conform to
> a well-designed DTD helps me maintain a constant awareness
> of structure at every level. Each choice about what element to
> use next is a structural decision. Structure and process get
> co-mingled, which is organic design..
What happens when the structure must be undone at a fundamental level? What
happens when the whole universe changes and all that information must be
unraveled and put back together - as is so common in high tech today?
You're stuck with a very well-ordered system that must be ripped apart and
rebuilt.
It is my assertion that you would have been better off to focus on the content
in round one since the structure will change anyways. We have a joke here in
the office about our docs: "We'll doc that to completion next rev."
Its an acknowledgment that some issues are in such flux, that building
exquisite tables and structures to support the concept would be a waste of
time. Best to throw together the facts and then let the reality percolate out
later.
Yes, some concepts eventually solidify into hard and fast laws, but until they
do, I am loathe to assign any meta-anything to them and fall in love with a
particular structure.
Andrew Plato
__________________________________________________
Do You Yahoo!?
Yahoo! Messenger - Talk while you surf! It's FREE. http://im.yahoo.com/
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Learn how to develop HTML-based Help with Macromedia Dreamweaver!
Dec. 7-8, 2000, Orlando, FL -- $100 discount for STC members. http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.
Your web site localized into 32 languages? Maybe not now, but sooner than
you think. Download ForeignExchange's FREE paper, "3 steps to successful
translation management" at http://www.fxtrans.com/3steps.html?tw.
---
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.
