Re: Single Sourcing

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 J. Ray RayComm, Inc. ejray -at- raycomm -dot- com

*Award-winning author of several popular computer books
*Syndicated columnist: Rays on Computing
*Technology Department Editor, _Technical Communication_

From ??? -at- ??? Sun Jan 00 00:00:00 0000=

Previous by Author: Getting Experience through Open Source Documentation
Next by Author: JOB: Contract position Concord MA Demo Producer
Previous by Thread: Single Sourcing
Next by Thread: Re: Single Sourcing

What this post helpful? Share it with friends and colleagues:

Sponsored Ads