Re: Single Sourcing

["Brierley, Sean" <Brierley -at- QUODATA -dot- COM>]

Hallo:

How to write true single-source stuff? I am really only just stepping into
that myself.

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.

Thus,

Head 1
drivel
Head 2
Steps

becomes

Head 1
drivel
steps.

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
help.

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 . . ..

Anyone else?

Sean
sean -at- quodata -dot- com



>>>-----Original Message-----
>>>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
>>>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
>>>

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