[Search for users] [Overall Top Noters] [List of all Conferences] [Download this site]

Conference vaxuum::online_bookbuilding

Title:	Online Bookbuilding
Notice:	This conference is write-locked: see note 1.3.
Moderator:	VAXUUM::UTT

Created:	Fri Aug 12 1988
Last Modified:	Mon Jul 15 1991
Last Successful Update:	Fri Jun 06 1997
Number of topics:	440
Total number of notes:	2134

76.0. "Formal or Informal?" by MTWAIN::SNOW () Fri Feb 03 1989 07:14

    How do other users of the Bookreader feel about the usability of
    informal and formal figures and tables? On page 1-3 of _Coding
    Documentation Source Files for the Online Bookreader_, it says
    "informal figures...should be somewhat incidental;  that is,
    useful and illustrative but not sufficiently content laden that
    they deserve a table of contents entry."
    
    We are putting the PVAX docs online, and made all our figures formal.
    In viewing them, though, I don't see the usefulness of the TOC entry. If
    a user takes the time to scroll down to the list of figures in
    the TOC and clicks on a figure, all she gets is the figure. No
    text. And no way to get to the text that discusses the figure.
     
    If a figure is informal and inline, then the user sees the text
    and figure at the same time in one window. This is the way most
    figures are handled in the DECwindows documentation. The only
    problem I found with inline figures was that the Bookreader takes
    a long time to "draw" the figure, and until the user becomes familiar
    with this, it's possible that she'll click on "Next Topic" or
    whatever before the figure even appears. But this is still preferable
    to formal figures, which pop up on top of the text and have to be
    moved in order to see figure and text together.

T.R	Title	User	Personal Name	Date	Lines
76.1	Formal looks better-Informal works better	CURIE::HARTSHORN		`Fri Feb 03 1989 10:30`	22
	The description of informal figures on page 1-3 of the "Coding Documentation Source Files...etc" is very vague and is open to a lot of interpretation. I think that formal tables in the BOOKREADER should be kept to a minimum. I have found that the new window that opens up is distracting and isolates the table from its supporting text. All of this becomes a problem when you want a formal table for the hardcopy but an informal table for the online version. In hardcopy a formal table does not have the above mentioned problems of online tables plus formal tables look better. One work-around may be to conditionalize those tables that you want as formal for hardcopy and informal for online. However, I have heard a lot of talk about conditionalizing files to work-around this problem and that problem. By conditionalizing you are essentially making two source files, one online, the other hardcopy. This defeats the premise of "One Source File, Two Outputs." I think that <CONDITION> tags should be viewed as a temporary fix.
76.2	it's flexible	STAR::KRAETSCH	NeXt Window Please	`Fri Feb 03 1989 11:28`	11
	Formal figures are popped up so that you CAN view the figure and the text simultaneously. Granted, you have to move the figure to see both, but it also gives you the flexibility of viewing the text OR the figure. If you want this flexibility and don't want a TOC entry, use <ONLINE_POPUP>. In the future, it may be possible to pop the figure up somewhere else on the screen (no promises though...). Another idea for the future is to have the "Table of Figures", etc. directly accessible, probably from the View menu, rather than having to scroll way down the TOC. joe
76.3		CLOSET::UTT		`Fri Feb 03 1989 14:59`	8
	RE: 76.0. Yes, my comments about when to use inline vs. formal figures, tables, and examples are pretty vague. I think this is something that needs some good guidelines, after we have more experience with what 'works' online and what doesn't. Donna Tramontozzi's Online Documentation Production committee has started putting together such guidelines, so hopefully some more information about options and alternatives will be available in the future.
76.4	Don't know the name of the town, but go north...	DONVAN::TRAMONTOZZI		`Wed Feb 15 1989 13:33`	6
	If there's one thing that could be said right now, it's DON'T LOSE ONE SOURCE FILE, MULTIPLE OUTPUTS The online poptag was "invented" to help solve this problem. If the figure looks better online in a separate window and it's not formal (which pops up by default), use the online popup tag.