Re: Techwriter's toolkits and directions for tomorrow (long and deep response)

["Bill Hall" <bill -dot- hall -at- hotkey -dot- net -dot- au>]

Shauna Iannone made some very thoughtful comments on the 22nd relating to my
post on "Techwriter's toolkits and 'application holy wars'" that I would
like to respond to now. I will also wrap into this response a number of
comments from the "Directions for tomorrow..." thread.

One comment from Shauna's post deserves headline status because I'm going to
cover some deep philosophy here: "Philosophical conversation becomes
navel-gazing when it is no longer applicable to something functioning in
your own reality, so I try to explore this paradigm conflict [as discussed
in my original post in this thread] with an eye to how it affects my
day-to-day work." My focus is very much on how the philosophical
understanding can influence the way we work.

Also there is a lot in the responses following on from David Neely's post on
"Directions for tomorrow's techwriting" that should help to focus on how we
work today and our need to anticipate how this is going to change in the
future.

The background for the philosophical discussion is my belief that
techwriters are the pre-eminent "knowledge workers" and we are in the midst
of fundamental revolutions in the way we capture and manage knowledge.
Techwriters have the primary responsibility to distil knowledge that is
initially only tacit - in people's heads, or implicit - as embodied in
engineering drawings, software or processes. This distillation process has
to produce as an end product something that is coherently organised and
codified for easy access and understanding by people who need to use the
knowledge we document. Sometimes lives depend on the accuracy, availability
and useability of the documentation so produced.

As knowledge workers, we unavoidably work immersed in paradigms of what
constitutes knowledge and of the document.

To discuss what I mean, I am going to start with some fairly deep
philosophy, then I'm going to consider Shauna's post - which also contains
some deep insights.

A clear understanding of what is meant by the term paradigm is essential to
this discussion, and I fear that I have still not adequately communicated
what this is in my previous posts. Hence a bit of philosophy - theory of
knowledge stuff - about paradigms. (I believe this is useful stuff for any
technical writer - who really needs to understand the paradigms the target
audience sees the world through.

Thomas Kuhn's 1962 book The Structure of Scientific Revolutions and his
later thoughts on scientific revolutions and later reprises provide the
definition of the concept of paradigm as I use it here.

The further works are

o  (1970). Postscript - 1969. in The Structure of Scientific Revolutions,
2nd Ed., Enlarged. University of Chicago Press, Chicago, 210 pp.;
o  (1977). Second Thoughts on Paradigms. pp 459-482. in Suppe (1977);
o  (1983). Commensurability, Comparability, Communicability. In PSA 1982:
Proceedings of the 1982 Biennial Meeting of the Philosophy of Science
Association, Vol 2. from Kuhn (2000); and
o  (2000). The Road Since Structure. University of Chicago Press, 335 pp.
[Posthumously published by Jehane R. Kuhn].
o  The reference for the Suppe book, which in my opinion still has not been
superseded as a comprehensive introduction to most aspects of epistemology
(the theory of knowledge), is: Suppe, F. (1977). The Structure of Scientific
Theories. 2nd Ed. University of Chicago Press, 818 pp.

There are, of course many more views, leading to lively debates on all
aspects of the ideas.

To quote and paraphrase from my Knowledge in Knowledge Management draft:

In Kuhn's most generic usage, "A paradigm is what the members of a
'scientific community' [or other knowledge-based discipline], and they
alone, share. Conversely it is their possession of a common paradigm that
constitutes a scientific community [i.e., discipline] of a group of
otherwise disparate men" (1977 pp. 460). Kuhn further notes that the
discipline will "to a remarkable extent... have absorbed the same literature
and drawn similar lessons from it. Because the attention of different
[disciplines] is focussed on different matters, professional communication
across [discipline] lines is likely to be arduous, often gives rise to
misunderstanding, and may, if pursued, isolate significant disagreement.
(pp. 460-461)" [This is the basis of the "incommensurability" of paradigms].

Kuhn, in responding to criticisms of his loose usage of his own term in the
1962 work, stated he was most concerned to use "paradigm" in the meaning of
a "disciplinary matrix" of shared exemplars of what the discipline
considered to be "good science". This includes four major components. From
(Kuhn 1977; Forster 1998):
o  Symbolic generalisations — deployed by authors without question or
introspection, and immediately understandable by the group,
o  Models — including those with heuristic and metaphysical presumptions
that provide the group with preferred analogies or even with an ontology,
and
o  Exemplars — which are unquestioned and accepted concrete examples of how
to solve particular kinds of problems or of what constitutes "good"
science — i.e., paradigms in the common English usage of the term.

Kuhn (1970:185), included a fourth component:
o  Values — in the sense providing a predictive or epistemic value: "values
to be used in judging whole theories: they must, first and foremost, permit
puzzle-formulation and solution; where possible they should be simple,
self-consistent, and plausible, compatible, that is, with other theories
currently deployed". Here he is talking specifically about the sciences. For
technologies I would say the values are what are used to judge the way
things work.

I follow Kuhn's preferred definition, and emphasise that Kuhn's concept of
paradigm includes the tacitly accepted a priori beliefs and theory or
assumption-laden vocabulary and jargon that members of the discipline accept
more-or-less uncritically along with their exemplars as they learn their
trade. The vocabulary used to describe and discuss symbolic generalisations,
models and exemplars is often based on unstated assumptions. Like most
vocabularies, theory-laden vocabulary is mostly learned tacitly "by example"
as part of the conceptual "world view" or "gestalt" within which the
discipline works.

Because paradigms are largely implicit (or even tacit), most people working
with a technology or science would not be consciously aware that their
thinking about their work rested on any such foundation. Consequently,
people working in the different paradigms can't talk to each other sensibly
even when they are using the same words, because the connotations associated
with the words and contexts in which they are used differ. Consequently,
different paradigms relating to the same broad subject matter are said to be
"incommensurable".

According to Kuhn, scientific (or technological) revolutions may occur when
new observations/requirements can no longer be adequately explained or dealt
with in an existing paradigm (the observations are anomalous), and can only
be accommodated in theory based on new exemplars, models and/or symbolic
generalisations. These changes often require new vocabulary and more often
alter the meaning, connotation and contexts of existing vocabulary. Even
where the same words are used within each of the paradigms, there is often
no longer a direct logical correspondence in their meanings. In other words,
the world view (created by symbolic generalisations, models, exemplars and
their associated theory-laden vocabulary) held by practitioners of one
paradigm is logically incommensurable with the world view held by users of
the alternative paradigm. Even when practitioners of different paradigms
look at the same data, they see different worlds.

"Holy wars" arise in a trade or science when more than one
paradigmatically-based sub-discipline is competing for the same members.
Members of paradigmatically different sub-disciplines can no longer
communicate within a single framework of shared beliefs, worldview and
vocabulary - and fail to recognize why the other guy remains so totally
witless and stupid even when they try to explain in the simplest way how
things work. It is easy to be frustrated with what seems to be obstinant
stupidity, and people quickly descend to name-calling and occasionally worse
actions. True communication is possible only if one can step far enough
outside of the paradigms to see and discuss in some kind of "metalanguage"
the normally tacitly accepted assumptions, exemplars and generalisations, to
see how these relate to the matter at hand.

If this all seems esoteric and theoretical, let's consider how all this
applies to our profession in the differences between "paper" and
"structured" document paradigms in techwriting.

Shauna's comments are interesting in reference to the complexity of the
paradigmatic conflict within technical writing:

"[I]t [is] easier to couch this part as the model by which we operate within
a context. One thing that seems to foster some of the conflicts between one
paradigm and another here is the miscommunication, or insufficient
identification of context."

Here he is referring to what Kuhn called "incommensurability". Identifying
contexts helps, but the "miscommunication" can result from differences in
understanding deep in the cognitive structure of different paradigms.

My text as Shauna quoted it:

> The issue that Andrew Plato and I fought our holy war
> over was the nature of the document. For many people
[...]
> a document is an object in its own right that is presented
> for use as a bound set of paper pages. It is written, used
> and managed as a discrete object with a clearly defined
> scope and purpose.
[snip]
> By contrast with structured documents, the focus is on the
> organization of the elements or "containers" of content
> within the document. Structure (e.g., SGML, XML - or even
> RTF if you are careful) can be defined and tagged
> semantically rather than in terms of formatted appearance
> to indicate the kind of knowledge held within the containers.
[snip]

Shauna's response:

---------

Both of these views can fit within the same object-oriented framework, if
you are thinking [of documents] as nested objects. The document as an object
has metadata (purpose, scope, versioning, packaging/associated docs,
storage/publishing location, etc.) that is outwardly-focused. The
document-as-collection-of-objects is the same sort of thing focused inward.
Each object in a structured doc has metadata focused "outward" to establish
its place in the doc, just as the doc has metadata that establishes its
place in the doc set or package it is a part of.

The thing I usually see that distinguishes the two paradigms more readily,
is the perception of a document's existence within a temporal continuum. To
explore this, an analogy can be made between docs and programs: from the
business perspective, both a program and a document have two types of
existence,...a terminal existence and a permanent existence. As part of
their terminal existence, they are deliverables, with a discrete beginning
and ending. As part of their permanent existence, they are evolving
organisms, requiring maintenance beyond their own self-contained anatomy.

---------

My interpolation:

Wow! Here Shauna has introduced a "metalanguage" - and it's done
brilliantly.

Shauna now adds two more brilliant contextual concepts - "system" versus
"project":

---------

Terminal docs fit more readily into the first paradigm you describe, and
permanent docs fit more readily into the second. The problem is, in the
quest for efficiency, these two types of docs overlap. Rather than rewriting
a doc from scratch every time there are changes made, "versions" of the
permanent doc are spun off as discrete docs over the course of a document's
life. (This works with docs other than software docs,--e.g., every revision
of a policy is just a "terminal" snapshot of that policy over the document's
lifecycle.)

I personally think of the terminal existence as "project" level, with the
permanent existence at a "system" level, because that's how they manifest in
my day-to-day existence. I recognize that these terms may not be the best to
use for other contexts. (...Right now, your exploration seems to touch upon,
or perhaps tangle with, something I'm trying to sort out in my day-to-day
work,--a way of bridging the gap in perspectives with some of my SMEs that
would make it easier for me to get the information I need for docs I
maintain.) Within this context, the project level feeds the system level,
but they actually exist in tandem. One system may be subject to many
projects, and one project may affect many systems.  This is where the
difference in paradigm can become painful and/or emotionally-laden for some.

If you view a doc as a terminal, or project doc, as a deliverable with a
beginning and an end, then thinking of docs from within the first paradigm
works better -- there is little or no need to categorize an element within a
doc for reuse, so the application of such process-intensive efforts will
appear to be a waste of time (and thus, Andrew's mantras against being too
process-focused). However, if you view a doc as a permanent, or system doc,
where your deliverable is its maintenance as a repository of selected
content, then thinking of docs from within the second paradigm works better
(and thus various people's arguments about a lack of process or certain
organizational/structural elements leading to a maintenance nightmare).

---------

Shauna's comments above deal very lucidly with the contextual differences
between paper and structured document paradigms, but only begin to touch on
the more profound differences between paper and structured in terms of how
we think about documents.

The paper paradigm has the image of a stack of pages with printing, which
implies an apparatus of printers, stapling, slow physical distribution,
physical filing, document control sections - and if you are lucky a register
or index to what the documents actually contain, etc. Beyond this you have
certain understandings about the importance of formatting. The person who
captures the knowledge is also responsible for layout and presentation.

Particularly when paper documents are seen from the executive point of view,
how the whole organization is run may be based on assumptions about whether
or how knowledge about systems, processes and procedures can be captured and
distributed in this tangible ponderous format.

Beyond this applications designed to support the paper paradigm focus
primarily on giving the author immense power (and applications that are
inherently fallible due to the complexity of offering authors multiple ways
of creating visibly similar formats), with no thought to understanding,
using, managing, retrieving or delivering the electronic content of the
document.

By contrast, when one starts working seriously with structured documents,
the paradigm one eventually learns is one of a virtual container for
semantically codified elements of knowledge are tagged for 'intelligent'
computer processing - where technologies now exist that allow either the
whole container or selected components to be queried from electronic
storage, processed, repurposed, and delivered at the speed of light to where
ever and when ever they are required. A tech author can realistically
provide current, distilled, codified and contextually relevant knowledge at
the fingertips of anyone who needs it, any time, any where - even in
situations the writer may never have anticipated.

Some hint of the possibilities inherent in the structured document paradigm
is given in my May 2001 Technical Communication article on the maintenance
documentation system we deployed for two national fleets of ANZAC Frigates:
http://www.tenix.com/PDFLibrary/91.pdf. By implementing fully structured
authoring processes along with technology for electronic workflow, we can
author, peer review, QA review and sign off, and deliver much higher quality
documentation changes than we ever could in the past. (The statement on
quality is our client's, not mine.) The purely electronic process delivers
the result into the Navy's relationally-based maintenance management
application, which in turn places a printed version of the current
maintenance procedure into the hands of a crew member as he sets out to
perform the task.

In converting our documents from the word processed format into structured
documents through to the point of delivery, our cycle time for the complete
process was routinely less than two hours - even for major edits which
involved turning single language documents into dual language ones,
paragraph restructure, reviewing and adding safety notes and verifying the
consistency of a large body of metadata with the text. If there is any need
to do so, the entire process from receipt of an authorised change to placing
the changed document into the hands of the maintainer who must use it can be
completed in less than 24 hours (not that we have yet had that specific
need - all we had to do was process around 8,000 documents in three
months!). This assumes the Navy (who is now directly involved in our
electronic workflow) completes their signoff, and then delivers the
documentation change to the ships by satellite within the remaining 22
hours.

In the structured paradigm, the techwriter's role becomes much more
fundamental to the organization. To repeat my statement from the top of this
post:

Techwriters have the primary responsibility to understand, distil and
translate knowledge that is initially only tacit - in people's heads, or
implicit - as embodied in engineering drawings, software or processes, or at
best - written in techo jargon. This distillation process has to produce as
an end product something that is structured (as defined in the common usage)
and codified for easy access and understanding by people who need to use the
knowledge.

In the past this structure was paper, where issues of formatting and style
played a dominant role in structuring knowledge for perception - if the
paper document could ever be found where and when it was really needed and
most of us became skilled typesetters and layout artists. In the future we
will all need to be knowledge and system managers (lower case "km") in order
to effectively carry out our roles to distil, translate and deliver
knowledge - and yes, this will have a major impact on our trade.

Large technology organizations will feel the impact first, but as the
enabling technology becomes less expensive it will filter down to the "lone
writers". My guess is that the process will take less than five years (how
fast has the World Wide Web grown?).

--------

What did others in the "Directions for tomorrow..." thread say:

David Neeley asked for "thoughts about the direction of technical writing
departments and practices in the near future. Specifically, I invite your
comments about my growing conviction that we will see a growing methodology
shift driven by increased understanding of the benefits of creating
documentation that is easy to re-use and maintain. It appears clear that
this will in most cases be through employment of XML and repository tools
based upon this technology."

Most early replies to David focussed on the very superficial issue of why he
might be spending so much time on formatting that he thought XML [i.e.,
structured documentation] would make his life any simpler.

Bernd Hutschenreuther took a broader view and suggested XML would lead to
major changes in the following areas:

1. Internationalization
2. Teamwork between producer and user
3. Interactive "intelligent" manual
4. Solution oriented
5. Multimedia
6. Simulation

Rebecca Downey accepted Bernd's view and added Internal localization to his
list.

My comment is that these will all be by-products of the paradigm shift, but
you've seen nothing yet. Changes will be much more radical.

Phil Levy, on the 24th, noted that, "When I suggest that there will be fewer
tech writers in the future, I mean that lots of work tech writers do adds
very little value. For example, doing research. Yes, seeking information is
largely, not completely, a duplication of someone else's work. I suggest
that someday developers/engineers will not mind (or will get paid for)
storing information so that a tech writer can find it, such as in an XML
file/template.

Connie Giordano says, "Which means writers may have to do what I've been
researching and advocating for awhile:  transform ourselves into user
support/product design specialists.  I do so little traditional technical
writing these days, they really ought to change my job title."

Christopher Gooch expressed the question in a new way - particularly with
regard to the typesetting language TeX, "My question, for those that are
interested in such things, is this; if you have already invested in using a
semantically rich and readable mark-up language such as LaTeX (with your own
macros for semantic elements), which gives you the best available
typesetting for free, is it worth investing the extra effort in moving to
DocBook or some other xml DTD, then introducing the extra step (conversion
from DocBook to TeX) for rendering to paper or PDF?"

Sandy Harris is beginning to focus on what I see as the central issue for
the future as our document paradigm changes from paper to structured:

--------

It is one thing to write terse documentation usable by another programmer
maintaining your code or by an expert user who already understands the
concepts in whatever domain you're working in, It is a different thing to
fully document a complex product, making it usable by a far larger group.

> After all, don't we tech writers spend a lot of time  and get paid a lot
of money for seeking information  that already exists? It seems fairly
absurd to pay for  something twice. The absurdity just hasn't registered  to
most companies yet. <

As I see it, we get paid to organize that information and make it
accessible... Methinks our role may change some, but we won't become
obsolete anytime soon.

-------

Bruce Byfield:

-------

[S]toring and reusing information is something that many tech-writers do
now. I know that, at several companies, I've put together libraries of facts
that everybody in the company would be using over and over: standard
language for introducing a product, feature lists, company bios and blurbs,
and similar stuff.

XML may help in this task, if the company's documentation is organized
properly, but I find it hard to think of it as anything more than another
addition to the tool kit. I've seen the introduction of several tools, and
been happy enough to have them, and I greet XML in the same way, but I don't
see it as the great change in direction that many people claim. No matter
what the tools, writers seem to end up doing much the same thing. They may
do them better, but the basic task doesn't seem to change.

--------

I agree with Bruce that our basic task is to understand, distil, codify,
translate and transmit knowledge will not change as we shift from one
paradigm of the document to another. However, I believe that the "change in
direction" will be much more fundamental than just learning to use new
tools,
as techwriters inevitably become knowledge managers.


Bill Hall
Documentation Systems Analyst
Strategy and Development
Tenix Defence
Williamstown, Vic. 3016 Australia
http://www.tenix.com
malto:bill -dot- hall -at- tenix -dot- com
------------------------------------------
Information is not knowledge
Knowledge is not wisdom
Wisdom is not truth
Truth is not beauty
Beauty is not love
Love is not music
Music is THE BEST
-----------------------------
(Zappa - Packard Goose)




^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Free copy of ARTS PDF Tools when you register for the PDF
Conference by April 30. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.com

Are you using Doc-to-Help or ForeHelp? Switch to RoboHelp for Word for $249
or to RoboHelp Office for only $499. Get the PC Magazine five-star rated
Help authoring tool for less! Go to http://www.ehelp.com/techwr

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