Re: Single-sourcing: the possible dream? Mif2go, etc.

[Larry Kollar <Larry.Kollar@xxxxxxxxxxx>]

Hedley Finger wrote:

>How did you accommodate the terse topic-to-a-small-page style of on-line
>help with the more discursive style for printed books?  How did you design
>the book pages so that the output has appropriate navigation: Next,
>Previous, Back, Forward, To Contents, To Index, Help/Web Home, etc.

This may be a topic better suited for techwr-l, but since I haven't
subscribed to that list, I'll expound here. (IMO implied throughout.)

If on-line content vs. printed content isn't a false dichotomy by now,
it's rapidly going that way. Even in printed documentation, people
are demanding brief, task-oriented manuals that address the job at
hand. I haven't made a page count, but I suspect that the breakdown
for our current product line documentation (approx. 4000 pages total)
looks similar to this:

  65% procedures
  25% reference (command descriptions and so on)
  10% discourse or explanatory material

I think each of these needs its own presentation (style/format) and
navigation aids, but I haven't nailed anything down yet. Navigation
is a large subset of the total problem:

  - Some things are easy -- commands used in a procedure should
    link to the reference page for that command, for example. We
    could also move discussion material to its own page ("for more
    information") and link to it from the procedure. Linking to
    procedures you have to complete before starting this one is
    another no-brainer.

  - Other decisions could go either way -- do we back-link from a
    command reference page to any procedure that uses that command?
    Does each step deserve its own page, or do we put the entire
    procedure in a single file? How much discourse material do we
    put online, and where do we link into (and out) of it?

Many of these navigation aids have print analogs, and we currently
use very few of them. We too are looking toward a single-source
future, and the more I think about it, the more I think we'll have
to restructure our printed documentation as well. Fortunately, we're
planning to do that anyway.

	Larry



** To unsubscribe, send a message to majordomo@omsys.com **
** with "unsubscribe framers" (no quotes) in the body.   **