Web Design

PURPOSE

Although I have been writing published articles about specific aspects of my work since the beginning of my career and I have always commented my code very well, I have not always succeeded in communicating with the full range of colleagues affected by my work. Early on I adopted the common arrogant engineer attitude of “read my code (or schematic) if you want to know what I’ve done.” I honestly thought that if someone couldn’t do this then they couldn’t understand what I was doing no matter how I might explain it. It took a long time for me to realize how wrong I was. My epiphany came during the BM-Hitachi 747 project. I was working with excellent engineers. They would understand my work from its existential documentation if anyone would, but they begged me to provide something besides my code to explain the test selection and result data flow between the control and analyzer units. It pained me to spend an entire day creating one simple diagram but the reaction of my colleagues convinced me that I needed to do this more often. More than pleased; they were grateful.

For the Abbott instrument development system (initially called CD3200R and later CDNext) I wrote more than 2,000 pages of documentation, nearly all text. I included a few diagrams, but using MSWord to draw diagrams is very painful. With the primitive tools provided, the initial diagram takes an inordinately long time to create. Then subsequent changes in other parts of the document cause object misalignments in the drawing. Adding one simple diagram to a document causes an enormous increase in the file size, complicating and slowing file transmission and version control. The documents were hyperlinked both internally (bookmarks) and to each other using the native facilities of MSWord and I created one document that served as a site map for all of the others. I expected this linking to be sufficient to get my colleagues to find answers to questions without my help. Wrong again. Not because they were dumb or lazy but because this much text simply intimidates people who are already confused and frustrated (otherwise they wouldn’t be looking at the documentation). I realized that I needed to present the information in a way that would not just be organized and accessible to a dedicated searcher but more inviting to everyone. This is clearly a job for the web.

WEB TECHNOLOGIES

Without a doubt, web technologies afford a significantly better way to present graphic content than native stick drawings in MSWord. Any tool can be used to create and modify drawings and photographs, which remain as separate non-propriety JPEG, GIF, and PNG/MNG files. Html documents can be under version control separately from the graphic files that they include.

Standard web technologies do not improve on MSWord’s hyperlinking capability. However, they afford more opportunities for useful extensions, some of which I will describe here. In any case, these days people are more comfortable looking for an answer to a specific question on a web site than in a mass of documents. This is of particular benefit if the documentation serves as on-line help as well as normal project information. Even the mass of MSWord documents that I wrote for CDNext saw significant usage due to certain documents, like the script language reference, being linked (both generally and by specific topics) to the script debugger running on an instrument. Web technologies would not only make this connection more inviting but could include additional sources of information, such as schematics and files located on other instruments or servers.

EXTENSIONS

I have developed a number of web technology extensions to support a technical web site. These range from generally useful facilities to items of utility only to this type of site. The extensions are implemented using JavaScript, CSS, and specific HTML coding techniques.

GENERAL ENHANCEMENTS

I have developed some enhancements to web technologies that are general and not specific to a technical web site. These appear throughout this site. Two notable ones are my smart text sizing and animated anchor.

The rationale for smart Text Size is that text serves two different purposes in a web page. Text in a paragraph is intended to be studied, while text in layout-sensitive containers, such as side bars and menus, requires only a quick glance. It can be a strain to study small text but increasing the size of all text degrades sensitive layouts. Smart text sizing addresses this problem by adjusting the size of only text that is intended for focused reading (identified by CSS class).

a:hover { 
  background-color: #fcccd4;    /* Pink until GIF */ 
  color: #0000ff;       /* Blue until GIF */
  background-image: url( aniblue4.gif); /* Light moving bars on very light blue. */
}

Even more than a technical site, general web sites are often very graphical, which can be interesting to look at but which can make distinguishing active links difficult. I have developed a general mechanism to clearly identify active links. When the cursor hovers over an active link (anchor) its background becomes animated in a way that is unmistakable but does not interfere with the foreground. The entire background field of the anchor is filled with shifting light bars, reminiscent of flowing water. This is done with a single animated GIF comprising only four 16-pixel images.The browser fills the entire background area of the anchor by expanding the image.

FLUID FORMATTING

Fluid formatting techniques allow browsers to fit pages into windows and devices of any reasonable size. This is particularly useful when the site is being used as on-line documentation, as it enables the browser to shrink to fit into a spare screen nook without becoming ineffective. It can also be useful to a technician viewing a technical drawing on a pad computer while examining an instrument. Although simple text is automatically fluid, many of the standard techniques for making a page more inviting, such as sidebars, encapsulate text in a non-fluid table. That most pages on the Internet use tables is immediately apparent when the browser window width is reduced; elements toward the right simply disappear under the right border. I have developed general guidelines as well as specific CSS and HTML code for effective fluid formatting without sacrificing layout control.

This page affords an example of fluid formatting. The Content section floats to the right of the left side (link) bar and it also flows out to the left body border after the end of side bar. A non-fluid layout using a table could also produce the sidebar but it would go to the bottom of the body even though most of it would be empty. Worse, because it would be one table cell while the Content section would be another cell of the same table, blocks within the Content, such as the code block below, may cause the browser to shrink the width of the link bar to share the pain of an inadequate window width. This makes the link bar not line up with the logo box above and forces links on to multiple lines, both of which look bad. The extra space it gives the Content section is minimal and usually not needed anyway (as in this case)

One obvious problem with table-based layout is that it forces the page designer to assume a certain window width. Users with a wider window can’t take advantage of the increased capacity. Those with a narrower window have to constantly scroll left and right, which is known to reduce comprehension nearly to zero. This is commonly viewed as “just” a problem for alternative devices, such as pad computers. However, in a technical application, like this clinical instrument web site, the user may shrink the browser window in order to keep other applications visible for viewing related information.

Browsers can change the width of table columns in response to changing window size. When a browser reduces a cell’s width it usually compensates by increasing the height. If a cell contains only text, the browser will reflow that text to fully utilize the available space. If the cell or another in the same column contains something of a fixed size, typically an image, when the window width is shrunk to the point of impinging on the image, the browser stops trying to flow anything in the entire column. If the browser supports local item scrolling (overflow: auto) it redraws the page with a horizontal scroll bar attached to the image. Otherwise, the right portion of the image disappears under its right border. In either case the browser stops flowing text in the same column, forcing the user to scroll left and right to read it. Having to scroll to see all of the image is only slightly inconvenient but such a requirement for text makes the text practically incomprehensible.

Layout control with fluidity depends primarily on the CSS float property and, to a lesser extent, margin. For example, the left-side “link” bar on this page is a div with the style declaration float: left. Without additional border, padding, and margin declarations the page would not look very good. These are defined in a separate CSS style sheet, for similar pages to share. Throughout its entire height, all page elements that appear later (in the HTML file) than the link bar float to the right. Additional layout control can be achieved by declaring subsequent elements float: left. Such elements still float to the right of all preceding elements. The right side of the page can be treated similarly using float: right elements.

Unlike table-based layout, floated sidebars stop where their content ends, allowing other page elements to flow below them. This produces an inconsistent left border that may be visually disconcerting to users more familiar with a long strip of dead space under side bars that have run out of content. There is no reason to mourn the loss of a huge blank space. For the page developer, however, this left border anomaly demands a change in layout techniques. The following discussion is based on a single left-floating element, the linkbar. The same issues exist for multiple floating elements.

For all content floating to the right of the linkbar, browsers ignore any left margin associated with block elements-- notably headings, paragraphs, lists, and tables-- adjacent to the linkbar. When these same types of elements are completely clear of the linkbar and, therefore, their left edge is next to the body border, browsers honor their left margin property. Browsers honor the left margin of inline elements-- notably anchors and images-- even when they are adjacent to the linkbar.

The simplest way to provide a gap between the right edge of the linkbar and the other page elements is by setting the right margin property of the linkbar. All elements to the right must honor this. If this is the only method used, all of these elements will be left aligned except for those that have text-align center or right property. Generally, exact left-alignment of all text-align left elements is acceptable. However, in the fully fluid page layout with left side bar scheme, major topic headings stand out particularly well if outdented left from the other elements. Self-control of the left margin can be regained by inlining. For example, if a left-aligned heading is given the style property display: inline, it can be outdented relative to the paragraph. However, this causes self-control of the bottom and top margins to be lost, complicating layout within the Content section. Control of both horizontal and vertical margins can be achieved by nesting the header content in a span within the header. The header controls top and bottom margin, while the span controls left and right.

The following examples from this page and from the external style sheet tech.css illustrate the fluid layout control means.

/* Linkbar is a vertical block along the left edge of the page. Text-align 
* margin, and border are defined for this arrangement. A bottom border is drawn 
* in case the page is fully fluid, with content able to flow under the 
* linkbar. */
.LinkBar {
  width: 149px; /* Props open the block to align with title bar logo. */
  float: left;  
  background-color: #c5d8ee;        /* Light gray-blue */
  text-align: left; 
  margin: 0 15px 5px 0; /* Right margin is for p in rightward panel. */
  padding: 0;
  border: 0; 
  border-right: solid 1px black; 
  border-bottom: solid 1px black; /* For fluid layout. */
}
/* TaskBar is a horizontal strip under the title bar and to the right of linkbar. */
.TaskBar { 
  border-bottom: solid 1px #000000;
  background-color: white;
  margin: 0;
  padding: 0 1px 1px 2px; /* top and bottom control bar height in FF/Moz and IE. */
  line-height: 19px; /* Controls bar height in FF/Moz. */
  text-align: left; 
  font-size: 16px;   /* Controls bar height in IE. */
  font-family: serif; 
}
.TaskBar ul { margin: 0; }
.TaskBar a { 
  text-decoration: none;
  white-space: nowrap; 
} 
.TaskBar li {
  display: inline; 
  margin: 0 .5em 0 0; 
  padding: 0; 
}
.Content { 
  margin: 15px; 
  padding: 0;
  background-color: white; 
}
.Content p {
  text-align: justify; 
  font-weight: 400;
  font-size:  15px;
  font-family: arial,sans-serif; 
}
.Content h2 { margin: 20px 0 0 0; } 
.Hout       { margin-left: -10px; }

<div class="LinkBar">
  <h3>This Page</h3>
  <ul>
    <li><a href="#purpose">Purpose</a></li>
...
</div>                <!-- ********** End LinkBar  *******  -->
<ul class="TaskBar">  <!-- ********** Begin Taskbar  *******  -->
  <li><a href="index.html#titlebar" title="To Home Page" >
...
</ul>                 <!-- ********** End Taskbar  *******  -->
<div class="Content"> <!-- ********** Begin Content  *******  -->
<h2 id="purpose"><span class="Hout">PURPOSE</span></h2>

FAR AND NEAR LINKS

Technical sites usually present multiple topics, each comprising a collection of pages. Hyperlinking affords random links between pages throughout the entire collection but sequential access is sometimes more useful. Therefore, many web documents, especially technical manuals, include prev and next links on every page. But this affords only sequencing within the one topic. My “near” links Prev and Next provide this level of sequencing while my “far” links Prev and Next extend this same capability to the higher-level topics. Page 1 provides a near home link, going to the first page of the current topic, while Home is the far home link, going to the first page of the entire site (which is normally the home page). For convenience, the user can sequence through the pages by mouse click or Enter key. When one of the Prev or Next links is invoked, the corresponding link in the destination page automatically receives the focus. Paging through the far or near page collection requires only an initial click on one of these links (or focus by tabbing) followed by repeatedly pressing the Enter key.

MULTI-LEVEL THUMBNAILS

A standard thumbnail gallery consists of a collection of very reduced images that serve as anchor points for their full-size version. Clicking a thumbnail image causes the browser window to change to the full-size image. I have improved the basic thumbnail concept by adding an intermediate size capability and by keeping both the intermediate and full size images in the gallery window, which maintains context more naturally than page jumping and avoids clogging browser history with superfluous jumps. The Multi-Level Thumbnail page illustrates how this capability might be used to condense pictorial access to all circuit boards in a complex instrument to a single page. Initially, each PCB is shown as a very small thumbnail. Rolling the mouse over one of these images causes it to be shown at its intermediate size, which is still small enough to minimally disturb page context yet may afford sufficient detail to satisfy the purpose of the visual query. If this is not enough detail, clicking the mouse button causes the full size image to display in place, i.e. not by jumping to another page. Clicking the mouse button again in any part of this image returns it to its thumbnail (or intermediate, depending on mouse position) size. If you test that page now, you will find that no matter how many times you change images, a single click of the browser’s Back button brings you back here.

IMPROVED IMAGE MAP

Image maps, like thumbnails, provide visual anchor points. With an image map, a single image is divided into regions. Clicking the mouse on a region activates a hyperlink. One problem with the standard capability is that link areas are not indicated. Internet Explorer draws a faint outline when the mouse button is depressed but until this appears there is no indication of the extent or even existence of the link area. As illustrated by the Image Map example page, my improved version outlines each area as the mouse passes over it. Another improvement is that rolling over other links (in the left side bar of the example page) cause related areas in the image to be outlined. A technician can point to a particular item or area of the image to discover what it is or, already knowing the topic, roll over its name in the side bar and see the related physical areas of the PCB.

INFO BUTTONS

In addition to the obvious text and images appearing on a web page, web technologies provide two means of accessing related information that is, in effect, hidden. Clicking an anchor jumps to a new page (or point in the same page) entirely out of context but capable of displaying an extended amount of information. In contrast, tool tips don’t change the page context but are difficult to control (just knowing whether one exists at a particular point requires some patience). The Info Button example page illustrates an intermediate form of in-page information expansion, affording a level between tool tips and a full URL. Rolling over an “info button” causes hidden information to be displayed. Rolling off causes the information to disappear again. Clicking the info button locks the information so that it remains displayed until the button is clicked again and the mouse rolls off. All hidden information can be displayed at once by toggling the Show Selected/All Info field at the top of the left side bar.

SPECIALIZED TECHNICAL FORMATTING

Much of the web-based documentation that I am targeting involves specific technical information, for example the unit ID number “9602330-rev P14” in the Image Map page. Such information should be presented consistently for both human and machine readers. The Specialized Styling section of that page describes some of the CSS and HTML conventions that I have developed to support this.