Untangling the Web
URLs in this document have been updated. Links enclosed in {curly brackets} have been changed. If a replacement link was located, the new URL was added and the link is active; if a new site could not be identified, the broken link was removed.

Instruction on the Web: Authoring Tutorials in HTML

Katherine M. Whitley
Reference Librarian & Coordinator of Computer-Assisted Reference Services
Science and Engineering Library
University of California, San Diego

Copyright 1996, Katherine M. Whitley. Used with permission.


One impact of the world wide web has been to level the playing field to a certain extent for publishing information by putting authoring and displaying tools in the hands of just about anyone who wants to play. At UCSD Science & Engineering Library, we have taken advantage of the web's instructional possibilities by filling a need to reach users at their own workstations with help materials. HTML provides an almost ideal vehicle for teaching methods that require visual impact, that take advantage of the hypertext nature of the web, and that can be used remotely.

As a result, I have developed two tutorials authored in HTML using a publicly available screen capture utility, a simple graphics editor and HTML editor software. I used a Macintosh to develop these tutorials, but will show that this approach is easily used in other platforms. There is a relatively short learning curve for constructing these tutorials, and I will show that just about anyone can do it.

One tutorial is a basic introduction to using Netscape, which also covers strategies for finding information on the web. The other tutorial is an in-depth guide to the Compendex online database.

I will share variant design concerns for tutorials, plus some tips and some pitfalls I discovered in the authoring process. I will also discuss using one of the Netscape extensions to HTML to create an automatic slide show that can also be controlled somewhat by the user. Finally, I am developing new versions of the tutorials that use the versatile "frames" feature of Netscape Navigator 2.0.


  • Why Web?
  • The Bare Minimum
  • Fancier Stuff
  • The Platform Question
  • Even Fancier Stuff -- The "Client Pull" Slideshow
  • To Frame or Not to Frame
  • What Does the Future Hold?

  • Why Web?

    Information providers like libraries are poised at the intersection of two eras--the era of the printed word and the era of electronic access. More and more information users rarely step foot inside the library walls, relying instead on an almost exponentially expanding body of digitized information available to them right in the location where they are doing their work.

    Systems for accessing information seem to be becoming more user friendly, but most systems still require some instruction for effective use. Libraries in the past have relied on printed documentation and "point of use" guides inside their buildings--but what about meeting the needs of users whose primary point of use is outside library walls? Remote use suggests using remote instruction methods, and the web, in addition to being the delivery vehicle for information, is also especially useful for delivering training.

    The visual and hypertext nature of the world wide web makes it a natural avenue for tutoring users of electronic information systems. HTML--hypertext markup language--is a standard method of transmitting information over different computing platforms and is readily accessible by even novice information providers (some would say too accessible!). Online tutorials for computer-based information systems allow easy inclusion of screen examples that can be costly and cumbersome in print format.

    This paper discusses several techniques for authoring tutorials for the world wide web, ranging from simple text to more complex graphical methods. Current versions of several tutorials are available at:

    The Bare Minimum

    It is possible to author training information at a number of levels of complexity on the web. The most basic method is simply to transfer printed guides to the net directly. But even this requires some additional thought -- there is not a 1-to-1 correspondence in just loading the text from printed materials to the web. The two mediums necessitate somewhat different approaches--adapt! The computer screen has different dimensions than the printed page, and you will need to experiment with different layout patterns to get acceptable results. Here are 3 basic approaches:

    Fancier Stuff

    The basic approaches described above will serve a wide range of uses. But, to use more of the capabilities of HTML for tutoring users of computer-based services like online library catalogs, databases or world wide web browsers, for example, graphic examples from actual screens of the applications are invaluable.

    First, map out your tutorial using storyboard techniques in a similar manner that you would use for planning a printed guide. What are the pieces of your message and how do they fit together. This is the time to think about hypertext links where they are needed to explain or augment your message. Remember to build in links back to your core information so that the reader doesn't get lost -- hypertext is terrific for branching out, but if you are trying to work your way through a body of material, maintain a logical progression as well.

    The Graphics

    Generate a script showing what screens you need to copy -- make printouts of these if you can to help you later with editing. Do the screen grabs using utilities like {FlashIt} for the Macintosh. FlashIt is especially useful since it offers options to capture the whole screen or portions of a screen and write to a file, send to a printer, and to scale the graphic up or down in size by 5% increments.

    [Sample of Flash-It

    If you don't have access to sophisticated graphics editing programs, do the screen grabs at 100% if you need to preserve detail in the screen display. Remember that in both VT100 ASCII screen displays and WWW browser screen displays, you can experiment with font size and color on the original screen to get the clearest effect. More on size and color below.

    Edit the screen grabs with a graphics editor to call attention to important points and to guide the user along. For the graphics used in the Compendex database tutorial, I just used the graphics editor that is included with Microsoft Word.

    [Example of adding graphics to a
Microsoft Word screen]

    Because I used the Microsoft Word graphics editor, I needed to do additional screen grabs of the edited screen grabs using FlashIt again. If you have access to a more sophisticated graphics editor, this step is unnecessary.

    Convert to GIF format using utilities like {GIF Converter}. This is a shareware program that converts common graphics file formats interchangeably. One nice feature is that it can do "interlaced" GIF files -- these load more easily on the World Wide Web.

    The HTML

    Once you have prepared the graphics files you need, the next step is to integrate them into HTML files. Even though HTML files are just text files that you can write with any text editor, try an easy HTML editor that allows you to check how your files will look in the browser -- I used {HTML Editor} written by Rick Giles of Acadia University in Nova Scotia. The newest version provides a template for your HTML file with buttons for easy coding.

    There are several excellent HTML guides on the Web: Spinning the Web, Eric A. Meyer's Introduction to HTMLan interactive tutorial, {Beginner's Guide to HTML}. Also remember that you can always copy the source HTML file for pages you especially like, using the "view source" feature of web browsers, and use it as a guide.

    The Platform Question

    Test your HTML files on different platforms -- Windows, Mac, Unix -- to see any obvious problems. Size, look, color, and arrangement can vary with the same browser on different platforms, with different monitors on the same platform, and with different browsers.

    Experiment with different placement of material for best effect.

    Remember that the typical PC screen is 640x480 pixels and that some of this space is taken up by the browser control keys and menus. This is particularly important to take into consideration with graphics, tables, and frames. Width is probably more important to consider than height, since most users have no problem with scrolling up and down, but do seem to dislike scrolling from left to right.

    Consider this problem of fitting a screen shot graphic as well as explanatory and navigational information on the same screen. The graphic needs to be large enough to be legible, but small enough to accommodate accompanying text.

    Here is an early version of a screen explaining how to do a keyword search in an online database, Compendex. Notice that it is annoying to scroll back and forth to view the screen grab graphic and that it is difficult to match the text explanation at the top to the graphic when you can't see the entire graphic.

    [Sample of a Compendex tutorial
screen showing the need to scroll repeatedly]

    Here is a later version of this screen with a smaller graphic that is still legible, but allows the user to match up the accompanying text with the relevant point on the graphic.

    [Sample of a Compendex tutorial screen
with a smaller graphic]

    Sometimes a smaller graphic is not the entire solution. Here is an early version of a sample keyword search in the Compendex database that is part of a slideshow (described below). Notice that the navigation bar, which needs to visible as much as possible, also makes it difficult to connect the explanatory material at the top with the graphic below.

    [Sample of a Compendex tutorial
screen showing difficulty in connecting text and

    Here is a later version that reorganized the navigation bar to the side of the graphic to take advantage of available horizontal space. But now it is easier to connect the explanation with the graphic.

    [Sample of a Compendex tutorial
screen showing better connection between text and graphic]

    Another technique that can help use all of the available screen space effectively is the "table" feature. Some word processing programs like Microsoft Word and WordPerfect offer table features that are similar to HTML tables. Tables are very useful for formatting data into columns and rows -- with only the space available on a computer screen, this formatting capability can be very useful. Early versions of HTML made displaying tabular or formatted data difficult to display in a compact yet meaningful way. The following screen would be a lengthier list of text without using the table feature. This example uses borderlines in the table, but effective use of tables can be made without borders.

    [Sample of Compendex tutorial screen
showing effective use of tables]

    Even Fancier Stuff -- The "Client Pull" Slideshow

    A recent HTML innovation by Netscape paved the way for "poor person's" animation -- "client pull." This is what makes the Netscape icon's comets shoot. But you can use this feature to create a rudimentary slideshow for portions of a tutorial where you need to demonstrate a logical progression from screen to screen.

    This sample -- {Compendex Conference Title Search Demonstration} shows one possible implementation of this feature.

    Here is how the first few lines of the HTML file for the first slideshow file looks:

    <META HTTP-EQUIV="Refresh" CONTENT="20;
    <title>Sample Searches - Word01</title>

    The screens change every 20 seconds -- this is what "Refresh" in line 3 does. The "CONTENT="20;" in the same line is the part of the HTML file that controls the time for refreshing the screen. Notice that this "META" HTML coding is in the heading of the HTML file, just before the title.

    Included in the slideshow are links giving the option to "Pause" the screen for more careful reading, to "Resume" the slideshow after pausing, or to go "Forward" to the next screen without waiting 20 seconds. The "Resume" and "Forward" links are just straightfoward links to the current page and the new screens, respectively-- "Resume" restarts the slide show with the screen where you are currently Paused, and "Forward" takes you to the next screen of the slideshow.

    The "Pause" link is a little trickier -- it stays in the same file, but goes to a named "target" in the file to keep you from being "pulled" to the next screen. Here is how the HTML for the "Pause" link looks:

    <A NAME="pause">
    <li> Press C on the COMPENDEX Main Menu to get the screen
    <li> Type as much of the EXACT conference title as will fit
    in the provided space, beginning with the first words of the
    <table border>
      <TD valign=center align=center width="100%">
      Screen 1 of 3<br>
      <IMG SRC="gifs/SAMPLECONF01.GIF">
      <td valign=top align=center>
      <a href="#pause">Pause</A><p>
      <A HREF="sampleconf-pt01.html">Resume</A><p>
      <A HREF="#top">Top of page</A><p>
      <A HREF="sampleconf-pt02.html">
      Remember! this screen changes every 20 seconds...

    The link for "Pause" -- <a href="#pause">Pause</A> -- looks for the target in the same HTML file -- <A NAME="pause">, and the screen remains until the user clicks on the "Resume" link to reload the current page and resume the slideshow.

    See Netscape's {explanation of client pull} for complete information about using this feature.

    To Frame or Not to Frame

    The latest development - frames provided by Netscape 2.0 browser -- allows more control of the screen space. It allows you to divide the screen up into sections containing separate HTML files. A common use of frames is to provide a constant table of contents on screen.

    [Sample of a screen showing use of

    But you can get into trouble with too many frames and illogical links. Use hyperlinks that draw people back or give the option to break out. Also remember to develop a "non-framed" version for users who don't have Netscape version 2.0.

    One other caveat about frames -- {navigating within a frame} works by mouse clicks, not by Netscape's directional buttons. So the users of your tutorial will perhaps need some orientation.

    The "framed" version of the Compendex database tutorial's sample search slideshows utilizes a screen partitioned into a small top section containing the navigation (contents) bar for the different types of searches and a large bottom section for the sample search slideshow. Here is a sample screen of one of the framed version screens that is also a link to the live version.

    [Sample of Compendex tutorial
showing the use of frames]
    [Note: Broken link to http://scilib.ucsd.edu/testbed/frames/SampleSearches.html removed 7/16/00 by ald]

    How do Frames work?

    The file structure for designing frames uses a master file defining the sections (the "frames") as to position and size. Then the HTML files for each frame contain the data and any links that target displays in other frames. Netscape has a detailed {guide on using frames.}

    Here is the HTML for the master file for the sample conference title search:

    <title>Compendex Sample Searches</title>
    <frameset rows="50,*">
    <frame src="searches.html"
    <frame src="sampleintro.html"
    This guide requires Netscape 2.0.  You will find a non-framed
    version <a href="/electclass/Compendex.html">here</a>.
    Notice that there is no <body> tag in the file. Notice also how the Netscape screen is defined by the <frameset> tags. Then each frame is defined by the <frame src> tags -- the file for the top frame is searches.html, and the starting file for the bottom frame is sampleintro.html. The searches.html file has links that control the files that will appear in the bottom frame.

    Here is the HTML for the contents of the top frame -- filename searches.html:

    <title > </title>
    <body bgcolor="#ffffff">
    <img src="gifs/ssbutn.gif">
    <a href="sampleword-pt01.html" TARGET="screens">
    <img border=0 src="gifs/wordbutn.gif"></a>
    <a href="sampleau-pt01.html" TARGET="screens">
    <img border=0 src="gifs/aubutn.gif"></a>
    <a href="samplejrnl-pt01.html" TARGET="screens">
    <img border=0 src="gifs/jrnlbutn.gif"></a>
    <a href="sampleconf-pt01.html" TARGET="screens">
    <img border=0 src="gifs/confbutn.gif"></a>
    <a href="samplesubj-pt01.html" TARGET="screens">
    <img border=0 src="gifs/subjbutn.gif"></a>
    <a href="sampletitle-pt01.html" TARGET="screens">
    <img border=0 src="gifs/artlbutn.gif"></a>
    <a href="/electclass/Compendex.html" TARGET="_top">
    <img border=0 src="gifs/retybutn.gif"></a>
    Notice that the links are targeted to the bottom frame by TARGET="screens" tags. Notice also that the target for the last link is "TARGET="_top", which is the frame code for exiting the frame. This link takes you back to the table of contents of the tutorial.

    What Does the Future Hold?

    Medium Tech Advances

    Many web information providers are making their tutorials and other information available in Adobe Inc.'s {Acrobat} "portable document format" (PDF). Adobe offers that Acrobat Reader software available free for downloading, but markets the file creation and conversion software -- Acrobat Exchange and Acrobat Distiller (educational price for the package is around $150). PDF easily integrates text and images and is available for all major platforms. Printing a PDF file can be done with excellent results on laser or deskjet printers.

    Higher Tech Future

    The wave of the future seems to be in software that includes runtime versions of software that are downloaded to the users' machines along with the data -- {Shockwave} and {Java}. This technology is available now on a few platforms and is expected to become more widely available.

    As with much of technology, this development is both a blessing and a curse. It makes more sophisticated interactions possible via the world wide web, but requires the author to be conversant with programming techniques and languages beyond simple HTML.

    HTML 3.2 Checked!