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.
Subject:Re: Single Sourcing From:"Brierley, Sean" <Brierley -at- QUODATA -dot- COM> Date:Wed, 9 Jun 1999 11:36:01 -0400
Hallo:
Can we really single source? I think not for every conceivable kind of
output. As close as I've come is FrameMaker and WebWorks publisher. Using
conditional text, I can specify some portions of my document as print-only
and others as online-only. Thus, I use FrameMaker for the printed output and
PDF creation (online book). I use WebWorks Publisher for online help
creation. By using these two tools I do single source. I do not edit my core
document to go from printed book to online help. Note that my HTML output is
limited to online help. I do not need to make web pages out of my FrameMaker
book. Here, I foresee a huge content and layout problem that, it seems to
me, precludes single-sourcing.
Do I want to single source? Er . . . no. Why not? I want my software
documents to complement, not duplicate, each other. For example, I want my
online help to be a reference document that describes all the software
options, dialog boxes, check boxes, and switches. I want to include
information on how to get tasks done immediately, information that can be
read in less than a minute. I want my printed book to be more of an
application and tutorial tome. I want a user to be able to pre-plan their
activities by reading the book before an action is undertaken. I want the
printed book to be more strategic, providing overviews, tips, and background
information to round out the product. In essence, I want the printed book
and online help to contain different information, not only different
chunking. As a user, I get frustrated if I fail to find what I need in the
online help document and then turn to the book and find the same failure
written the same way, word-for-word.
The irony is that this is the way I do business, currently. Why? Well, as
Christine points out when she writes "aren't we saying we will forever be
saddled with an almost impossible maintenance problem?", this statement
underlines one of the problems: project planning. If you want a printed
book, and online help, and an online book, and you want to update it
frequently, and you insist on changing the GUI based on wind direction, then
you must add more writers, provide a later deadline, and/or not get what you
want.
If the software, or whatever it is, changes weekly, and if printed and
online output is required, then you need a plan. The plan must account for
these things, including deadlines, cost, and staffing levels. Perhaps the
plan would require that visual changes for a product could not be made
weekly, lock in a quarterly or semi-annually release cycle, invest in
technology and training to make single-sourcing work, discard single
sourcing and increase staffing, discard one or more output options as
unnecessarily expensive or unreasonable . . ..
So, can we single source? Maybe. I suppose that depends on what you mean . .
..
All the best,
Sean
sean -at- quodata -dot- com
>>>-----Original Message-----
>>>From: Christine Pellar-Kosbar [mailto:chrispk -at- MERIT -dot- EDU]
>>>Sent: Wednesday, June 09, 1999 11:06 AM
>>>To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
>>>Subject: Re: Single Sourcing
>>>
>>>
>>>Okay,
>>>
>>>I hear you all saying that you really can't single source --
>>>that web-based doc is
>>>inherently different in structure and complexity that print.
>>> So, of course, there
>>>is no technological solution -- no matter how hard I look, I
>>>won't find some
>>>combination of Frame/webimport-export software that will
>>>allow me to create both
>>>HTML and PDF versions of my doc. Well, if that is true,
>>>then aren't we saying we
>>>will forever be saddled with an almost impossible
>>>maintenance problem? If you have
>>>essentially two (and in some cases, three, when you include
>>>your training doc) sets
>>>of documentation, what happens when the content changes? In
>>>my case, the content
>>>changes weekly. I'm concerned that I will never be able to
>>>keep up with snapshots
>>>and releases if I have to constantly focus on consistency
>>>issues between these sets
>>>of documentation. Is there no simple solution? I had hoped
>>>that something like
>>>conditional text in Frame would allow a simpler web version.
>>> Perhaps I am dreaming.
>>>
>>>Christine Pellar-Kosbar
>>>Technical Writer
>>>Merit Network, Inc.
