Conference vaxuum::online_bookbuilding

97.0. "Problems Using Online Doc for Reference Manuals" by STAR::NELSON () Fri Mar 10 1989 19:08

The following report was not originally written for NOTES, but 
Mary has suggested that I enter it here so that everyone can 
benefit from her responses. While the issues I describe are 
specific to the NCL reference manual, many of them probably apply 
to designing ANY reference manual for online use. 


	PROBLEMS USING ONLINE DOCUMENTATION FOR REFERENCE MANUALS

   This report addresses an assortment of problems I have encountered
   while testing a new template that will be used by writing groups all
   over Digital to document the new NCL language.  NCL is a complicated
   language unlike anything we have ever had to document before, so it is
   a good test to see how DOCUMENT performs in extreme circumstances.

   Where I have found a temporary workaround to a problem, I have
   described that too -- along with any disadvantages it presents.

   Abbreviations used below:

   HC = hardcopy manual
   OL = online documentation


   1  RUNNING HEADS

   It is critical that readers have a running header that includes the
   entity name for the command description they are reading.

   In HC, we use double running heads:  the top line (coded with
   <command_section>) states the entity name; the second running head
   contains only the command verb (derived from the <command> tag).

   In OL, only the second header (the command verb) appears in the
   running head.  This is useless without the entity name because there
   will be dozens of commands with the same verb described in this
   manual.

   IDEAL SOLUTION:

     OL supports double running heads.

   WORKAROUND:

     I can include the entity name in the <command>(VERB\ENTITY NAME)
     tag.  This causes both the verb and the entity name to appear in the
     single OL running header.

     Disadvantage:  HC and OL appearance suffers from having unnecessary,
     overbearing text included in the command heading on the first page.

     Perhaps a way around this disadvantage would be to tell DOCUMENT to
     ignore the entity name UNLESS the doctype is online, and then tell
     it to use the entity name only for the running head and not as part
     of the command title.  (DOCUMENT is going to have to check to see if
     a manual is NCL anyway because we already know we must use a smaller
     font size to accommodate the running heads (see Section 2.1).)


   2  FORMAT/DESIGN PROBLEMS

   2.1  Running Head Font Size

   NCL entity names used in the running heads are so long that they run
   off the page in both HC and OL if the standard font size is used.

   IDEAL SOLUTION:

     Create an exceptional font size to be used for this manual.  (We
     have already had to do this for HC.)


   2.2  TOC Formats

   The command description chapters have only two tags that create a TOC
   entry:  <command_section_head> and <command>.  This combination
   creates odd formats in both HC and OL, but the OL version is
   especially hard to decipher.  (Keep in mind that neither of these tags
   produces a numbered level head in the TOC.)

   In HC, the section head appears in large print in the left margin.
   The command head appears in smaller print and is indented from both
   the right and left margins so that neither the command name nor the
   page number lines up with anything else in the TOC.  (In the NCP
   manual, this narrow format often causes the command line to wrap.)

   In OL, the section heads and the commands appear in the same size font
   and are both aligned at the left margin.  There is NO visual cue that
   one is subordinate to the other.

                                    NOTE

           It's curious that OL treats  <command>  like  <head1>,
           yet   HC   indents  <command>  items  even  more  than
           subordinate levels.

   IDEAL SOLUTION:

     For OL, either indent <command> entries in the TOC or use a smaller
     font for them.  (The former solution would correspond more closely
     to the HC TOC.)

     For HC, align command entries and their page numbers with those for
     all other TOC entries.


   3  USING THE BOOKREADER

   3.1  Placement of Popups on the Screen

   Popups are a wonderful tool -- except that they popup over the text
   I'd like to refer to while I'm reading the popup.

   IDEAL SOLUTION:

     Have the popup window popup beside the main window instead of over
     it.  If you think some folks may not want to obliterate their
     TOC/index window, then offer users a chance to specify whether
     popups should default to the right or left side of the screen.

     Unfortunately, I will choose NOT to use popups in some places if the
     inconvenience of popping them up over text I'm reading outweighs the
     tedium of scrolling thru text I may not need to refer to.


   3.2  Indexing Items in Popup Windows

   I can use popup windows to great advantage for "hiding" very detailed
   information that many users may wish to skip over.  It is easier to
   scroll by a "Click here" note than to scroll thru the text included in
   a popup (especially if it is several pages).  However, it is important
   that I index all the items included in these popup sections.

   The problem arises when I click on an index entry that takes me to
   popped-up text.  There is no running head that tells me where I am in
   the manual; there is only the short header for the popup itself.  When
   I exit from the popped up text, I do not find myself in the related
   text from which the popup originated -- I find myself back in the
   index!  This path renders useless the information I may have gained in
   the popup because I haven't a clue which command description I popped
   up into!

   The popup capability is probably the biggest boon to creating a fast
   and highly usable online reference document.  Unfortunately, its
   advantages are rendered useless by this indexing glitch.

   IDEAL SOLUTION:

     When an index entry takes a user into popped-up text, clicking on
     Close Topic should take the reader into the text from which the the
     popup window originated -- not back to the index.

   WORKAROUND:

     Never index items in popup windows unless the item is 100%
     meaningful on its own and the reader would not want to refer to text
     surrounding the popup or to know which topic the popup relates to.

     HUGE Disadvantage:  I can't speak for all books, but users of the
     NCL Reference Manual will pay the price of having to scroll through
     considerable text that they are not currently interested in just so
     that on the occasions when they do click on an index entry, they
     will be able to interpret the indexed item within a meaningful
     context.

     NCL is complicated enough in itself.  We'd like to make the
     documentation as easy to get around in as possible.


   3.3  A Wish:  To Have More Unreferenced Hotspots

   In command description sections, no level heads are permitted except
   for the command itself.  The reader must scroll through all
   information without benefit of Next Topic.

   Some of my command descriptions could be as long as 15 HC pages.
   Users generally are looking for specific categories of information
   within that 15 pages and probably will not need to read all of it.

   There are a number of ways that having either a Next Topic or hotspot
   capability would make moving through a command description much more
   convenient for the user.  For instance, each command description
   proceeds from an overview to very specific information.  If there were
   hotspots (like in the TOC or index) that a user could click on to move
   to the next deeper level of information on that topic, that would
   greatly speed up their finding the information they need.  (I guess a
   search capability could serve the same purpose, depending on how it is
   implemented.)

   Also, in my manual, it could be useful to be able to advance to a
   particular command description, but <command> does not permit a
   symbol-name as <headx> does.

   IDEAL SOLUTIONS:

      o  Provide a Next Topic capability within command descriptions.

      o  Provide a hotspot capability within command descriptions to take
         users to the next deeper level of information on a specific
         topic.  (This concept is different from Next Topic.  The hotspot
         would move to a related topic, but not necessarily the next
         topic.  I can show you examples of what I have in mind.)

      o  Provide <command> with a symbol-name field (like <headx> has.

      o  Provide a search capability.

    1. Running heads: I agree -- better and more levels of running heads
    would be nice. We have talked about this somewhat, and it's definitely
    a post-V2 (Bookreader) item, but we have discussed using additional
    windows at the top of the text window (under which text would scroll  
    so the running heads would, in fact, be stationary as the text moved).
    
    2. Running head font size. Right now the Bookreader selects the
    font size adn displays the running head (this is one case where
    the Bookreader does *not* use text formatted by DOCUMENT -- we simply
    pass it the ASCII string and it displays it). We know we need a
    better way to do it and if we can use formatted text in the running
    head window, we can alter the point size for specific doctypes.
    Note, however, that DECwindows supports many fewer font sizes than
    do PS printers and often finding a good font size is a challenge,
    but this too should change in the future (i.e., DECwindows should
    be adding more sizes to the video font repetoire).
    
    3. TOC formatting: the inability to discern heirarchy in this case
    sounds like a formatting anomaly that could be solved. I assume
    it's specific to your book since I  haven't had similar complaints
    (do you use a special doctype?). I'd need to look at your specific
    problems and requirements to figure out a solution.
    
    4. Placement of popups: Note 20 has some discussion of this. It's a
    difficult problem because what you consider a good place to put a popup
    another user might think is absolutely the wrong place, depending on
    what else you have running in other windows on the screen or personal
    preference or whatever... But it's *very* easy to move windows wherever
    you want them in the DECwindows interface, and believe it or not, I
    think that's the right answer. Screen real estate is *always* going to
    be at a premium, for all applications, and someone is always going to
    occlude someone else, and in different ways at different times, which
    makes it hard, if not impossible for any application to figure out
    where is the 'right' place to put things on the screen.  So, the
    interface needs to make it easy to iconize, push and pop, resize, and
    move windows to help alleviate occlusion. 
    
    (A better notes conference for a discussion of this, if you want
    to pursue it, is the BOOKREADER conference on BULOVA.)
    
    5. Indexing items in popup windows: good point. Similar problems
    occur if you go to a figure, table or example from the TOC -- you
    have no way of getting to the section that refers to it. This is
    on the wishlist for a future version of the Bookreader.
    
    6. Template information: you are right. We need to do *lots* better
    with templates, beginning with symbol args to <command>, etc. (A
    note just a few notes previous to this also makes this request:
    it's high on my wishlist, too.)
    
    One approach we've discussed is to bring up templated information
    with a 'short form', probably overview and syntax and a menu of
    the other, more detailed topics that the user could click on (lengthy
    description, examples, whatever.) Very often you don't want the
    whole 15 pages of text -- you may only want to refresh your memory
    about the syntax, perhaps check out a specific qualifier or whatever,
    and look at a couple of examples. Menus and popups on line can make
    this sort of perusal a whole lot easier. You can simulate this with
    <online_popup>s. For example:
    
    <description>
    <online_popup>(description)  [NB: online popup tags must be *within*
    ...paragraphs of text...          the <description>/<endescription>,
    <endonline_popup>                 as shown here.]
    <enddescription>
    
    In the output, you get the Description header, followed by the
    hotspot. 
    
    Thank you for some thoughtful analysis and good suggestions.
    
    Mary

    This is a fascinating note, showing a lot of thought.  It seems
    to me that for references inside commands (to qualifiers and parameters
    in very long commands for example) you need something more
    like helptopic? as in online help.  This would be an ideal that could
    go on some kind of very futuristic wish list. 
    
    Of course if the reference manual is already online as a helpfile,
    this might be a redundant exercise.

The best solution to the "pop-up window placement" problem is to have the formal 
figure or table pop up as it does now, allowing users to drag it to a new
location. 

Then, the  next time they pop up a window, it should appear in the same location 
to which they dragged the last one. 

This lets them pick whatever location they want pop-up windows to appear in.

I will welcome suggestions about placement of popups, but there is no right
answer.

It disturbs me when writers avoid using popups because they personally do
not like where the current version of the Bookreader places them.

We make things like formal figures popup so that the reader CAN view the
figure and accompanying text simultaneously or independently.  Yes, they
do have to move the figure window to see both (at least in version 1).
However, if you place your figure inline, the reader cannot view that 
figure with any test that does not fit in the same screen.  Remember that
some readers will be using smaller screens, whether on a PC or because they
shorten their topic window to save screen real estate for other windows.

The hardcopy analog of the popup is where you have text on one page and the
figure on the facing page.

joe

    Humm.  I'm puzzled.  I can't imagine why running heads would be
    needed for online pubs.  It's quite clear why they can be
    advantageous for hardcopy pubs (i.e., used as locators), but online
    pubs don't "work" this way -- do they?  Why would you use this kind
    of visual cueing mechanism for online?
    
    Maybe I'm missing something.  (This has happened once or twice before.)
    
    \ken

    In the case of the MILSPEC doctype, for example, security information
    is output at the top and bottom of the hardcopy page, in running
    heads and feet. Since this information is mandated by the government,
    we would need to provide capabilities for outputting this information
    online.
    
    Mary

    Responding to 97.5, I need double running headers at the top of my
    online ref manual to identify the entity and verb for which the 
    text I'm reading applies. Without that critical reference point, 
    the text I'm reading is useless. This is especially true if I come to
    this text from the index.