Designing hypertext for both online and print

["Chuck Martin" <cm -at- writeforyou -dot- com>]

I'm looking for some additional ideas to use in my current situation. I have
a few already. Here's the deal.

I'm using RoboHelp X4.1 to create user assistance for a Web-based
application that runs within Internet Explorer. Although I'm an Army of One
at this company, I have no choice currently as to the tool choice,
espeically as I came onboard near the end of the development cycle. The
primary output is WebHelp, but a PDF file is also desired.

I've been designing content with the primary output in mind. In doing so,
I've created links in a number of different contexts, and in many ways, I do
so to make topics themselves smaller.

I wrote eHelp a couple of days ago asking this:

"The company where I'm working wants printed output as well as WebHelp.
Naturally, when creating a hypertext system, there are extensive links.
Problem is, when I generate printed output, the only option I seem to have
is the resulting formatting of links.

What I need--what anyone would need--is ocnversion of links to cross
references, and the ability to define the style of cross references.

For me converting the WebHelp text "See _About_Projects_" where "About
Projects" is the link, I'd want to convert this to "See About Projects on
page ##," where "About Projects" is italicized and ## is the resulting page
number.

How do I do this with your product?"

The response was:

"It is not possible to convert hyperlinks to cross references.  When printed
documentation is created, all hyperlink information, except formatting is
stripped out."

Well, after I asked the question, but before I received an answer, I
realized that even the solution I was seeking wasn't going to work
everywhere. It would in two specific places: where I have a bit of content
and then a "See [Topic name] sentence where "Topic name" is a link, and
where I have a See Also section at the bottom of a topic followed by one or
more linked topic titles.

However I have many, many in-text links, including within procedural steps.
And I'm not sure what to do about these. For example, I have many topics
with a procedure structure similar to this one:

To edit a Risk

  1. View a Risks Detail Form.
  2. Make any desired changes. blah blah blah....

In this case, the first sentence has two links:

The word "View" is a link to a generic "Viewing Detail Forms" topic that has
one step with many options, thanks to this application's many ways of doing
things:

To view a record's Detail Form

  - In a module list view in Read Only mode, click the record number or name
or double click any field of the record that is not a link.
    -or-
    In a module list view in Editable mode, double-click any field of the
record.
    -or-
    In a module list view in either mode, click a field that is not a link,
then click Details. The Detail Form for that record appears.

The words "Risks Detail Form" is a link to another topic by the same name
that provides information about the options specific to that form.

The first link is so I don't have to repeat the "Viewing" information over
and over and over again in each topic, making each topic where it is
relevant longer. The second link is so that I don't have to duplicate
describing the details in multiple topics too.

Thing is, even if I could convert those links usefully to cross references
in printed output, how would they be useful? I've thought about using
conditional text, where the content would be duplicated in every procedure,
but then why not just put it everywhere and create situations where users
would rarely see all the procedural information without scrolling.

It seems awkward to create a construction, instead of my example, that says
something like:

1. View a Risks Detail Form. (See _Viewing_Detail_Forms_ and
_Risks_Detail_Form_ for more information.)

One thought is that I'd mark that parenthetical sentence as Print Only. Any
way I slice it, I'm going to have to go through the resulting printed
document and manually create hundreds of cross references. So why not at
least put the text in the source files?

When considering solutions, I also have plenty of instances of construction
such as this:

If a project schedule file is associated with the Project InVision Project,
enter Tasks by _checking_out_the_project_schedule_file_, adding the Tasks in
the project schedule file, and _checking_in_the_edited_file_. (The
underscores represent inline links.)

I don't see any way of making these links into cross references. Rather, the
only way I see it working is to add a parenthetical (See....) after each
in-text link everywhere. (Which also sets up the added load of finding where
each of those links was in the printed output.)

I should note too, for those who might not think that generic topics are
useful, customers can customize the application, adding modules, changing
module and field names, etc. One of the things I've done is to design
content where I can so it fits whether users are seeing the out-of-the box
configuration or a system that has been heavily customized to fit their
workflow.

I did a project a few months back where the beginning tool was also
mandated, but it was FrameMaker, and it's web-based output from heavily
cross-referenced print-oriented source turned out pretty well. Whether we'd
have the resources to switch development tools I don't know, but if I stay
around that long, the goal is to re-architect the user assistance solution
to be server-side database driven, and I could get excited about designing
and implementing such a system. That, however, is future, and I'm looking
for ideas that fit the constraints I face now.

Many thanks in advance.

Chuck Martin



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ROBOHELP FOR FRAMEMAKER TRIAL NOW AVAILABLE!

RoboHelp for FrameMaker is a NEW online publishing tool for FrameMaker that
lets you easily single-source content to online Help, intranet, and Web.  
The interface is designed for FrameMaker users, so there is little or no
learning curve and no macro language required! Call 800-718-4407 for 
competitive pricing or download a trial at: http://www.ehelp.com/techwr-l4

---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.