Re: Single Sourcing

[Sarah O'Keefe <okeefe -at- SCRIPTORIUM -dot- COM>]

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

Hi Eric,

There's a technical white paper that may help:

http://www.scriptorium.com/templ.pdf

In general, I'd suggest the following:

* Think in terms of modules. Write documentation in small, digestible
chunks. These will become HTML files, so make them stand on their own.
* Navigation is critical. Plan it carefully and don't be reluctant to add
additional navigation where necessary (via information embedded using
conditional text)
* Templates are good. Overrides are bad.
* Especially for reference information, look into providing search features
for the HTML
* Graphics can be tricky. For example, a "standard" setup is a graphic
followed by a caption with a figure number. When translated to HTML, all
the cross-references to the graphic actually point to the caption. When you
click on a cross-ref (now a hyperlink), the caption appears at the top of
the browser window, which means that the graphic is *above* it and doesn't
show up unless the user scrolls up the page. Consider either putting
captions ABOVE figures, eliminating them (not a great solution), or setting
up the conversion to move the captions from below the graphic to above.
* Make sure that callouts, if any, are legible in the HTML output.
Generally, this means your callout will need to be at least 10pts.
Helvetica or Univers is excelllent for reading online.
* Remember that the content of your master pages and any untagged flows
will not translate into HTML. You may want to take advantage of this to put
information there that's more appropriate for print.
* Be careful with the use of these words: following, next, previous, above,
below (and other "positional" descriptions.

It's a start...

Good luck!

Sarah

*************************************************************
Sarah O'Keefe           Scriptorium Publishing Services, Inc.
Author, FrameMaker for Dummies (available 8/99) 919-481-2701
WebWorks Publisher certified trainer   okeefe -at- scriptorium -dot- com
http://www.scriptorium.com

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