Overview

• Invent technologically-new authoring and production solutions on a product-by-product basis.

• Purchase and learn expensive off-the-shelf help authoring packages, which often resulted in a "splitting" of the source, such that one set of source files in format "X" were needed to support documentation deliverables, and another set were maintained in format "Y" in order to derive on-line help.

• Deliver one or more on-line documents, accessed from a help access object on a Graphical User Interface, and call the deliverable "on-line help".

Reasons for Development and Implementation

• Graphical User Interface

  Graphical user interface development teams within Lucent began moving away from using operating system-specific, proprietary development and display tools, towards web-based, cross-platform DHTML interfaces displayed using HTML 4.0, CSS, Java (TM), Javascript, and most recently, XML.

  These GUIs are capable of performing all communications between the server and clients via HTTP protocol, displaying the resulting data upon user terminals in HTML via off-the-shelf internet browsers.

• Lucent Corporate requested that a unified look and feel for on-line documentation and help deliverables being integrated with the new DHTML GUIs be developed. These new on-line designs were to be implemented across all products implementing the new GUIs, regardless of the product's (or customer's) server/client operating systems.

• Economic and quality directives within Lucent's technical authoring division resulted in an authoring platform unification initiative, in which proprietary desktop authoring environments began to be replaced with a standardized, enterprise-wide SGML publishing platform.

• single source

  Extensive studies determined ways of implementing "Single Source" information reuse strategies, which allowed efficient methods of creating different "types" of information products (standard documents, student guides, instructor guides, and User Assistance) from a single set of common source files, as well as different output formats for a single type.

• Information Mapping

  Case studies and trials conclusively proved that Information Mapping authoring methodology, coupled with Task-Oriented presentation practices were effective in lowering the expense and time intervals previously required to author and produce technical information products, regardless of type or presentation format.

Overview of User Assistance System Functionality

Output file format and technical details

• file granularity

  The overall User Assistance system, and all files within it are the result of one-time production runs. The output is produced by project authoring teams and delivered as a static set of files which are then integrated with the product GUI.

• All output file content, menus, and controls are coded using HTML 4.0 and Javascript 1.2.

• When the source documents are processed to produce the User Assistance system, all output files are chunked with a hierarchical level of granularity that occurs at theinformation map level. As an example, a chapter of source content which contains three information maps is converted to a single HTML "menu file" connected to three individual map-level HTML files, as shown .

  File splitting diagram

User Assistance system invokation from a GUI

• Using a relative path, which assumes help files are co-resident with GUI files under the same webserver.

• Using an absolute path with URL, which allows help files to be located on a different webserver than that used by the GUI .

• Using a token string, which is a combination of variable values that establishes uniqueness for each GUI page or object. This string is resolved into a URL by the Javascript functions within "help.js". The token string values are abstract values by design, which allows the GUI and User Assistance development environments to deviate on agreed system identifiers within source files by resolving the values within an indirection table.

Major User Assistance components

Help (task) component

Description (descriptive) component

• Description

  concepts  context sensitive  descriptions

  This component contains conceptual and descriptive information about the uses and function of the page or object within the GUI. Such information might describe what controls are available on a page, what a control or object on a particular page might be used for, and how it is used. When selected, the User Assistance window is invoked, in which the descriptive information is presented, with a "common functions" toolbar visible at the bottom of the window.

  Description file

Support (technical support) component

Interface Tips component

Library component

Toolbar components

• hypertext index   search  search for tasks

  List of Tasks

  A single file that contains a hyperlinked, permuted index of entries found withintask files that are accessible under the "Help" button.

• glossary

  Glossary

  A sorted list of terms that are used within the User Assistance system and their corresponding definitions

• Interface Tips

  One or more files containing information about common conventions supported by the GUI.

• hypertext index   search

  Find a Topic

  A single file that contains a hyperlinked, permuted index of entries found within both the task files (under the "Help" button) and descriptive files (under the "Description" button).

• go back  navigation

  Go Back

  A Javascript function which invokes "history -1" to recall the previous page that was loaded.

Overview of SGML Publishing System

• Standard Technical Documents

  PostScript®   PDF   HTML   DynaText®

• Student Guides

  PostScript   PDF

• Instructor Guides

  Postscript   PDF

Description of Source Information Content Models

• The DTD supports the creation of large, hierarchical documents, possessing publishing info, front matter, Parts and/or Chapters, followed by optional Appendices, and backmatter.

  High-level structure of authoring and production DTD

SGML Source Files and Context Associations

SGML source file requirements

Attribute values and allowed positions

• UA-Page-ID

  This attribute is used to contain a "token" or ID that associates the content of a container element in the source document with a particular GUI screen or object.

  This attribute is available on the following elements:

  Chapter   Appendix   All *-Map elements

• UA-Type

  This attribute is used to mark certain content within the source document as being associated with a particular UA component type.

  This attribute is available on the following elements:

  Chapter   Appendix

  The two attribute values currently allowed include:

  Interface Tips   Allows a chapter to be identified as the content which underlies the "Interface Tips" button.   Support   Allows a chapter to be identified as the content which underlies the "Technical Support" button, if a Tech-Support homepage is not used as the target for the button.

Attribute processing rules

Task Components and the UA-Page-ID attribute

<proced-map ua-page-id = "401 402 1012">

Description components and the UA-Page-ID attribute

<chapter ua-page-id = "401">

Interface Tips and Support components and the "UA-Type" attribute

<chapter ua-type = "interfacetips">

Output Processing Options

• Application-ID and Version-ID - (strings)

  The Application ID and Version ID strings are required prior to production. These strings are used during the output directory construction, and are also written to the "help.js" Javascript file and used by the "token-to-URL" resolution process.

  These values allow multiple versions of User Assistance to be integrated with different versions of a GUI on a single system, and/or allow multiple product GUIs to coexist on a single system without context collisions when invoking their respective User Assistance systems.

• Localized Path Name - (path name)

  This is the path that connects between the GUI invoking the User Assistance system, and the "help.js" file that controls the User Assistance system. Depending on implementation schemes, the User Assistance files may be coresident with the GUI in the same root directory, or may be installed under a different webserver. Because of these options, this value may be a relative path, an absolute path, or absolute using "http://...".

• Create Task Selection (Help) files? (yes/no)

  This is a simple boolean switch that allows the suppression of the task-based User Assistance component files that lie underneath the "Help" button.

• Create Conceptual (Description) files? (yes/no)

  This is a simple boolean switch that allows the suppression of the concept-based User Assistance component files that lie underneath the "Description" button.

• Create Technical Support files? (yes/no)

  This is a simple boolean switch that allows the suppression of the technical support User Assistance component files that lie underneath the "Support" button.

• Create Interface Tips files? (yes/no)

  This is a simple boolean switch that allows the suppression of the interface tips User Assistsnace files that lie underneath the "Interface Tips" icon in the toolbar.

• Create/Update Help.js Javascript file? (yes/no)

  This is a simple boolean switch that allows the suppression of the User Assistance javascript file. Once created, the file does not need to be created again.

• Create Glossary? (yes/no)

  This is a simple boolean switch that allows the suppression of the file that lies underneath the "Glossary" icon in the help toolbar.

• Create Master Index? (yes/no)

  This is a simple boolean switch that allows the suppression of the file that lies underneath the "Find A Topic" icon in the help toolbar.

• FTP Help files to new destination when finished? (yes/no)

  This is a switch that allows files to be transferred to another machine upon completion of job processing. If selected, a machine name and an incoming directory for the files to be transferred to is then provided by the user. This function, combined with scheduled-executution scripting, allows nightly builds of User Assistance to be created and subsequently delivered to the product team's GUI development machine or integration testing environment automatically.

Output Processing System

Graphics Handling

• TIFF

• EPS

Standard inline presentation of graphics

Large thumbnail presentation of graphics

• The HTML conversion tool sets the largest dimension of the illustration (height or width) to the value of the threshold, and calculates the smaller dimension so that the resulting image maintains the original aspect ratio. These new values are written as "Height" and "Width" attributes of the <IMG> element, and results in the "large thumbnail" which displays nicely within the borders of the default User Assistance window.

• A stand-alone HTML file is created that contains the Caption of the illustration, as well as the illustration itself with its "Height" and "Width" values taken directly from the source instance. This allows the illustration to be displayed in its original size in an independent file so that users can view details as needed.

• The "large thumbnail" image in the original HTML User Assistance file is contained within an HREF action to the new "Illustration" file. This allows users to select the thumbnail as a hyperlink in order to view a larger copy of the illustration, if necessary. As can be seen in the associated figures, the "thumbnail" is of a limited resolution, but there is enough detail for a user to recognize the type of illustration underneath it.

Cross-Reference and Link Handling

Xref element authoring and processing rules

<chapter id="123"><title>Title of Chapter 123 </title></chapter>
.
.
.
<para>For further info, see <xref linkend="123">.</para>

Results in:

For further info, see Title of Chapter 123.

• Chapter/Appendix (contains Title)

• Section (contains Title)

• All Map elements (contains Title)

• All Block/Subblock elements (contains Label)

• Figures/Tables (contains Caption)

• Steps/Stages (contains autonumbering sequences)

Link authoring and processing rules

Output Directory Structure and File Naming Conventions

Future System Enhancements

Production system enhancements

• Full internationalization support to allow translated, or non-english source documents to be converted to HTML UA and display icons and tooltips in the correct language.

• Conversion processes to obtain Microsoft® HTMLHelp deliveries by postprocessing the context-sensitive components of the User Assistance system.

Authoring system enhancements

• The ability to change or delete all occurences of a single UA-Page-ID value across the entire document instance.

• A mechanism to filter the editorial display to only include the content that would be included in an HTML UA output by virtue of UA-Page-ID/UA-Type attributes, and Xref/Link connections.

• The ability to obtain a "structure-view" like list of elements that support UA-* attributes. This interface would also allow the application of a specific UA-* attribute value to several elements in one operation.