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.
Michael Hoffman (S&T Onsite) sent an interesting post about the whole
single sourcing discussion, to which I reply:
Seldom have I read a post on this list with which I agree so completely.
See comments interspersed below.
| Some myths may have been started by consultants who
| wanted to sell their specialize expertise and techniques
| for online help.
How very true. And what will these people do if the rest of us ever
succeed in puncturing the myth that printed information and online
information are "fundamentally different" and must be authored
separately and independently using completely different sets of "rules"?
| I'd rather see consultants selling their
| single-sourcing expertise.
Well, as a consultant who sells his expertise in designing and
implementing single source solutions, I'm not so sure I agree here.
Wouldn't want the field to get *too* crowded. *bg*
| Single-sourcing
| skills are a superset of Help development skills.
| Many of the myths are due to tools limitations. Technical
| writing notions about document design have been influenced
| by tools limitations.
Yes, yes, and yes.
| Please see my in-depth coverage of this subject.
| http://www.hypertextnavigation.com I need a better
| title for the site, emphasizing universal document
| design for rapid knowledge transfer,
| rather than emphasizing hypertext or online
| documents. The central article is
| http://www.hypertextnavigation.com/infoaxcs.htm -- Enabling
| extremely rapid navigation in your web or document.
This is a very good article. Anyone actively involved in creating
complex online information sets should probably read it.
| The above article gets to the core of the matter, though what's
probably
| missing the most is discussion of conditional text for navigation
| elements and title pages.
Yes. So many of the arguments against single sourcing rely on the
shibboleth that content and writing style must sometimes vary between
printed and online versions of an information set, and, since this can't
be done in a single source environment, single sourcing doesn't work.
The problem with this argument is that true single sourcing IN NO WAY
prevents authors from varying content and writing style in various
output formats. I think sometimes these impressions have been formed
because authors have attempted to single source using tools that simply
do not support single sourcing (e.g., RoboHelp), and sometimes because
authors have simply never tried to implement a real single sourcing
environment.
There is no question in my mind that single sourcing can work and work
exceptionally well, enabling organizations to improve quality and
productivity at the same time. (Note: to head off another argument
frequently made, I am not saying that single sourcing is the right
solution for every project.)
| I've long thought that single-sourcing is the most
| important and overarching subject in the profession of
| technical writing, because it draws in all the document-design
| considerations of print and online help. There are challenges
| and limitations to single-sourcing. Many of these are
| actually tools limitations; they could be solved through
| further improvements of the tools.
It's true that there are limitations in the tools, and of course that
the tools can all be improved. The biggest tool problem I have observed
is this: author attempts to single source using a tool that does not
support single sourcing (e.g., RoboHelp) and then concludes, "Single
sourcing doesn't work." This is not entirely the author's fault since
the vendor is often claiming that the tool supports single sourcing even
though it does not mean the bare minimum criteria. The limitations are
much less significant with tools that support true single sourcing
(WebWorks, MIF2GO, and others).
The biggest problem I have observed, though, when single sourcing
solutions fail is not tool-related. It is instead, a failure of document
design and of multi-output authoring. It is not trivial for an author
accustomed to "multi-sourcing" (writing separate content for separate
output media) to make a successful transition to authoring single source
documents. The tools provide very little support for making this
transition (I'm not sure that they can), and authors moving to single
sourcing often do not get sufficient training, consulting, and other
support to make the transition successfully. In fact, many authors and
managers seem not to realize there is a transition to be made. Result:
author writes a printed document, generates an online version, and is
dissatisfied with the result (or vice versa). Conclusion: single
sourcing doesn't work. In a single sourcing environment, authors can no
longer write "printed documents" or "Help systems." They must instead
write single source documents. (I have long thought about offering
training on this precise subject but remain unconvinced that managers
and authors recognize the need for this kind of training.)
| The technical writing industry overemphasized surface bells
| and whistles (adding hundreds of features on top of a weak
| document-design foundation) rather than fundamental structures
| such as single-sourcing puts on center stage.
Absolutely. Bells and whistles are not where it's at. Solid document
design, information structure, and content are the fundamental
requirements. True single sourcing *can* impose discipline in these
areas, which usually ends up as a net benefit for authors and users
alike.
| Single-sourcing is the key to document design
| theory; if you understand single-sourcing, you understand
| structured print design and structured online-document design.
| The heart of single-sourcing is *document design theory* and
| I'd sure like to see much more discussion of this subject,
| not only day-to-day tools troubleshooting questions.
Yes, in our industry we ask far too many questions about, say, how to
implement popups with JavaScript and far too few about how to design and
write effective content.
| What's missing is a standard vocabulary to describe source-file
length,
| scrolling length, and inline subtopics. Currently the weakest link in
| the chain is weak support for authoring and using anchored subheadings
| (<h2><a/></h2>) from Contents, Search, and Index. The conventional
| notion of a "Help topic" is oversimplistic; we need a design framework
| that includes rich structure within a topic -- inline subheadings and
| inline subtopics.
And we're getting there one step at a time. These structures can be
implemented with FrameMaker and WebWorks Publisher (or MIF2GO) and will
be possible for Word users when Quadralay releases WordHelp. With
FrameMaker 7 in structured mode, it becomes even easier to design and
implement structure across a document set. Other tools will follow along
in time. However, the real question is will we, the authors, be ready?
Consulting & Training on FrameMaker & WebWorks Publisher
Consulting & Training on RoboHelp
WebWorks Publisher Certified
Member, JavaHelp 2.0 Expert Group
Moderator, HATT & wwp-users
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Buy RoboHelp Deluxe starting at only $798: you'll get RoboDemo, the hot new
software demonstration tool that's taking the Help authoring world by storm,
together with RoboHelp Office. Learn more at http://www.ehelp.com/techwr-l
Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.
---
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.
