sgml and single-source documentation

[mpriestley -at- VNET -dot- IBM -dot- COM]

Dave Walker (walker -at- aspentec -dot- com), replying to Noreen Casey (casey -at- osf -dot- org),
wrote in support of the viability of single-sourcing for online and
hardcopy.  Noreen was concerned that hypertext would be boring and
uninteresting, without adding features that simply wouldn't translate to
hardcopy (making the single-sourcing problematic).  Dave felt that much of
the information could be adequately written for both sources, and then if
necessary additional bells and whistles could be added to the online info
afterwards.

Now, I've been working primarily online for the last year or two, and am now
faced with the prospect of single-sourcing for online and hardcopy.
I'm looking forward to it as an interesting challenge, but I do (so far)
take a dimmer view than Dave Walker.  I think I'm going to have to compromise
the usability of the online information to make the single-sourcing feasible.
(I would love to be proved wrong!  I haven't tried yet, so I'm arguing
a priori here).  Some forms of presentation are inherently more usable in
one medium than the other, and not all of online's features are of the bell
and whistle variety.

Example1: automatic links between topics (so that a chunk of text that is
important in several different contexts, can always be included in those
contexts).  The user can make the same link in hardcopy, but it isn't
automatic, it's liable to be on a different page (necessitating page-flipping),
and probably an entirely different solution would be more effective.

Example2: "graphic" links: parts of a bitmap have "hotspots" that can
bring up related information (text, sound, or another bitmap, or it runs a
program....).  Schematic diagrams in hardcopy (with letters or numbers
providing a "link" to other information) provide some equivalent functionality,
but not all, and with considerable awkwardness.  I don't think there's any
existing automation for this.

Example3: any highly interactive or animated information.  This is part of
the spectrum of online information, and can usefully and effectively be
incorporated into more conventional hypertext.  If you go hardcopy, this
stuff will have to be just cut out.  Lopping off a limb of your documentation
isn't an attractive prospect, but if the online information is fully
integrated (and if it isn't it should be) then the operation becomes less
like an amputation and more like a triple-valve bypass.

So, my feeling is that the decision to single-source documentation _does_
limit your options online.  Single-sourcing makes the documentation set
easier to maintain, and more likely to be consistent.  If there are going
to be multiple releases of a product, there's a strong economic incentive to
single source.  It makes sense in a lot of ways.  But I think it's fair
to realise that there are trade-offs.  Actually, I doubt anyone would
disagree with that, but I wanted to draw attention to the magnitude of them,
since I don't think they're trivial.  There are things you can do online
that you can't do (at least effectively enough to be useful) in hardcopy, and
I'm sure vice versa.  When you single-source, you limit your information to
the subset of presentation methods that the two media share.


Thanks for the thought-provoking,


Michael Priestley
mpriestley -at- torolab4 -dot- vnet -dot- ibm -dot- com
Disclaimer: my views do not necessarily reflect those of my employer or anyone
else.  My head hurts, I'm probably hallucinating, and I shouldn't be held
responsible for anything I've said, done, or implied in the last, oh,
twenty-odd years.