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:Thu, 10 Jun 1999 15:31:11 -0400
How to write true single-source stuff? I am really only just stepping into
To do this I have moved from Frame+Word+RoboHelp and Word+RoboHelp entirely
to Frame+WebWorks Publisher. Picking what I perceive to be the right tools
for my plan was a big step. Enough about tools . . ..
The plan. Given time and budget constraints, including staff, I planned and
am writing a single document in FrameMaker that will be the printed book and
the online help (the former is distributed as a PDF, as well).
Selecting an online help format was a big step, also. I single-handedly
selected MS HTML Help for my company, as my offer for a discussion of the
subject was dismissed due to lack of time. Previously, previous writers
created WinHelp-based 32-bit help. MS HTML Help is a good choice for me
because my audience must be using an MS 32-bit OS. Furthermore, my audience
must have IE4+ installed (though it need not be their only browser). MS HTML
HELP has the advantage of being compiled and distributable as a single file.
If it were not MS HTML Help, I would try Quadralay's multi-platform help.
My company is not yet using context sensitivity and I am taking advantage of
this to ease my learning curve with the new tools and output.
For writing the single-source document, it is clear all must be in one FM
book file. I created two conditional cases, printonly and onlineonly.
Introductory drivel gets tagged printonly and reference information about
all the dialog box switches gets tagged onlineonly, for example. I also had
to adjust the way I wrote things and setup headings. For example, wherever
possible a heading is followed by the meat of the topic and not introductory
drivel and another heading.
This was necessary because Head 1 becomes its own HTML page, as does Head 2;
this leads to Head 1 topic containing only useless banter or nothing if the
conditional text is applied.
I am also writing to avoid using Head 4 and 5 as much as possible. Certain
styles, like bullets and numbered steps, I already keep to two levels max,
but had I not I certainly would have had to reign-in really complex
numbering arrangements. Further, I am pretty good about how I chunk
information in my books, I like to think they are written for
short-attention span folk, and this translates well when going to online
Additionally, I always have been pretty good at using templates and avoiding
local, case-by-case overrides. With single-sourcing, for cleaner
one-push-of-the-button conversions, I am especially careful about sticking
to templates. This way, if something doesn't work in one output format or
another, I can change it globally fairly easily. Also, there are no
surprises hiding in the doc that were caused by some localised override.
I still don't quite have the hang of graphics. I did do away with my
predecessor's use of figure numbers, which were never actually referenced
anywhere, and this has saved me some hassle. I am also pretty good about
capturing my images within a tight resolution and pixel-size range. For WWP,
this makes the conversion to GIF a little less hairy. I cannot wait for more
standard application of vector-ish images on the web!
I hope this mish-mash of thoughts provides some useful information. As my
projects evolve, I will have a better idea of what I did right and wrong.
Certainly, I am currently involved in reworking and updating projects that
were done by writers long-gone. These are proving difficult because I do not
have the time for a re-write . . ..
sean -at- quodata -dot- com
>>>From: Eric J. Ray [mailto:ejray -at- RAYCOMM -dot- COM]
>>>Sent: Thursday, June 10, 1999 11:49 AM
>>>To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
>>>Subject: Re: Single Sourcing
>>>Following up on the single sourcing thread, I'd like to
>>>open a discussion about writing techniques for
>>>single sourcing (Tim, others?)...
>>>Here's the context:
>>>As some of you know, I've been struggling through some
>>>requirements definitions for online help for a relatively
>>>new product. The second release is just starting development
>>>and the online help must be completely overhauled.
>>>(I wrote it, so I can say that it's not particularly helpful
>>>and certainly far from ideal.)
>>>I've investigated and nearly rejected JavaHelp (performance),
>>>ForeHelp's Interhelp (performance, support issues, Windows tools
>>>aren't ideal for our needs), and Blue-Sky's WebHelp (same as
>>>Plain HTML is good (and essential as one output format),
>>>but the last minute overhead of substantial changes
>>>in hand-coded HTML-based help systems puts a severe blemish
>>>on that solution
>>>as well. Sigh.
>>>Additionally, we're somewhat resource-constrained (4-5 writers
>>>worth of work, 2 or maybe 3 actual writers).
>>>Thus, the only really viable solution is that something has to give
>>>somewhere--the schedule won't, the resources won't magically
>>>appear, and a UNIX platform is preferable (all else being equal).
>>>Writing in Frame and converting via WebWorks Publisher looks
>>>like the overall best solution, and it _could_ let us single source
>>>hardcopy and online information, which would also help the
>>>So, with that context, how would you organize or structure or write
>>>for optimal single-sourcing? Conditional text is an option, of
>>>course. The information in question ranges from end-user how-to
>>>instructions through administration how-to (coupled with a Web-based
>>>admin GUI) through (possibly) programming reference material
>>>and API documentation.
>>>Ideas? Again, we've done the tools to the death--I'd really like
>>>to hear about writing and organizational techniques.