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:"Eric J. Ray" <ejray -at- RAYCOMM -dot- COM> Date:Thu, 10 Jun 1999 09:48:54 -0600
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 Interhelp).
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
resource issues.
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.
Eric
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Eric J. Ray RayComm, Inc. http://www.raycomm.com/ ejray -at- raycomm -dot- com
*Award-winning author of several popular computer books
*Syndicated columnist: Rays on Computing
*Technology Department Editor, _Technical Communication_
