Re: Techwriter's toolkits and "application holy wars"

[SIANNON -at- VISUS -dot- JNJ -dot- com]

OK, let me respond with those immediate thoughts prompted by the postings 
I've seen so far on this thread.

Bill Hall writes:
[snip def. of "paradigm")
> Because paradigms are normally absorbed implicitly as 
> more-or-less tacit knowledge, we are not normally 
> consciously aware of them.

I think your definition may be over-complex for discussion at a level that 
bridges both the theoretical and the practical (substancial). I find it 
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.

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

Both of these views can fit within the same object-oriented framework, if 
you are thinking 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.

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. (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 with an eye to 
how it affects my day-to-day work. 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).

Both are correct, in the right context(s).  My opinion (and here's where 
I'd be curious to see what your whitepaper opines on the matter, since I 
doubt my opinion matches all that many people) is that a fusion of the two 
paradigms is possible, and even desirable. I am currently exploring ways in 
which this might be accomplished. (I don't expect it to be easy, given that 
it is essentially an attempt to effect a cultural shift in a manner that 
doesn't jar participants from either quarter.)

Will a shift in paradigm alleviate "application holy wars"...? I doubt it, 
as the app's are but tools, and as such are merely wielded as weapons in a 
battle of philosophies; wars exist independently from either the 
motivations or the armaments of either side. However, a shift in these 
paradigms may have a significant positive impact on our day-to-day work.

Anyway, that's my feedback for now,
Shauna Iannone



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

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

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