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.
How not to write for single-source - top this! I was surfing the web,
online, one hand on the mouse and one on the keyboard, when I read this: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/odeopg/html
/deconforeword.asp -- "Congratulations! If you're reading this foreword,
you're either using, or considering using, Microsoft® Office 2000 as a part
of a custom solution. Either way, the book you hold in your hands is the
best available resource for learning how to exploit the programmability
features of Office 2000."
Writers would be wise to remain agnostic about delivery format when
composing, and write in a way that can be universally delivered. I don't
know why but I've always been inclined to think first in terms of
single-sourcing. Paper and screen are both just flat surfaces. A book is a
book, whether on a flat paper or glass surface.
There is definitely something "different" about my thinking style, my
analysis style -- I'm finally starting to realize this and identify what the
difference is. I should be able to contribute some unusual perspectives
that could help the online-document community.
For all the tools and viewers of the past decade, there are still some
*basic* mandatory features that no one is paying any attention to. Instead,
the various tools just repeat the same mistakes of WinHelp. What is HH,
JavaHelp, WebHelp, but the same old limited WinHelp with a different skin --
merely WinHelp workalikes.
To any 1980s hypertext theorist, the technologies of the past decade have
made little real progress; it's not coming together yet into a sane and
effective doc-delivery solution. Over here, we have HyperCard for Windows
-- aka WinHelp/HH -- and over here, we have a chaos of HTML pages -- and
over there, paper as usual.
My ideal would be WebHelp integrated directly into the browser, with
auto-extract sitemap while you surf, with print-as-article with page
numbers... and by the way, live editing capability, including live outline
manipulation.
My extreme single-sourcing mentality may be because I'm more of an abstract
thinker than others. Other people always seem to be incredibly concretistic
to me.
It's always been natural for me to think of a book not as something on
paper, nor as a particular help viewer, but as an information set -- some of
my early work at IBM using BookMaster/BookManager may have given me this
more abstract way of thinking.
There are no paper books versus electronic books; there are simply books
floating in the abstract ideal realm, that sometimes touch down on paper,
sometimes on glass. But the paper is not the book, the glass is not the
book.
I sure like the strong trend toward multiple compile targets in the
authoring tools: compile for WinHelp, HH, print, HTML, JavaHelp... this
makes people let go of mistaking the medium for the information.
Another indication that I come from a more abstract way of thinking is that
it has always bugged the heck out of me when people say a rock group has
released "a new CD". No, an artist does not go into the studio to record a
CD, but rather, an album of songs. The CD is just a stupid piece of plastic
on which the great album is stored. The CD may die, but the album is likely
to continue and will reside on some new media.
Concrete, grounded, and specific thinking is also needed. I dislike
academic theorizing that is all lost in gee-whiz notions, ungrounded by
concrete realities such as the features that support a comprehensible
structure.
I might consider academic theory as too imaginative, without the check of
practicality. I felt that way about Microsoft's theoretically justified but
practically meaningless usage of "choose" instead of "click" (they have
recently come to accept reality; now they say "click" because people can
make sense of such a wording).
The ideal practices and theories have a harmonious marriage of theory and
practice; the ideal is applied theory. For example, in theory, every print
construct maps to an online construct; an ideal single-sourcing system would
strive for full equivalence (and effective design details) of each specific
construct, such as printing with page numbers from online.
I have about 7 features to propose be refined in each of the online viewers
or for print format. Perhaps each feature could be considered as an idea
abstracted from various hypertext systems. One such feature is full,
first-class support for the HTML anchor aka bookmarks aka inline subtopics
aka in-flow subsections aka whitepaper subsections.
In some ways, this idea comes from considering hypertext documents in a more
abstract way than is usually done. In some ways, this idea comes from
specific features in viewers I've delivered docs in. Considering my
approach to guitar processing equipment and philosophy of religion, as well
as document structuring and presentation, I'm definitely more abstract in my
approach to subjects -- but I'd never elevate pure abstract thinking style
above concretistic thinking; both should be fully utilized together.
If someone asks me how something should be accomplished, I'd typically state
some principles as well as giving some specific solutions. The early 90s
deliberately exagerrated the differences between online and print, but
*practical* theory was needed to show how to achieve both in one shot,
effectively.
The tools we have today are based on non-single-sourcing foundations. Word
was designed for print only. WinHelp was designed for online only. The Web
was designed for online only. WinHelp and the Web thus have abysmal print
capabilities (no print-as-article with hierarchical TOC and page numbers
autogenerated, for example; graphics are split across pagebreak, styles are
lost, can't specify page range to print, and so on).
I'm buying tools now, and am considering what I need, what I want, and what
is available, and what solution to invest in -- but generally, the way
documents are authored and delivered is falling short of what I keep
assuming should be available by now after all these years. It's hard,
researching, learning, and testing, and analyzing all these different tools.
The popular techwriting tools don't make it as easy as I would expect to
ergonomically work on source files across the development team and simply
click a button (or do nothing) to produce online viewable and printable
docs.
A landmark hotel, one of America's most beautiful cities, and
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe. http://ieeepcs.org/2001/
+++ Miramo -- Database/XML publishing automation. See us at +++
+++ Seybold SFO, Sept. 25-27, in the Adobe Partners Pavilion +++
+++ More info: http://www.axialinfo.comhttp://www.miramo.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.
