Report: WinHelp Conference '95, Seattle, WA

[Trevor Grayling <TREVOR -at- MDLI -dot- COM>]

(Note: Long message.)

As attendees at the recent WinHelp Conference '95, my colleague Frank Ripp
and I were required to produce a report (groan).  We're sending the report
(slightly edited) to this mailing list so that: (1) Other attendees who still
have to produce reports can cut and paste stuff from this one if they wish,
saving themselves time; (2) Folks who didn't attend can get an idea of the
conference contents.  Of particular interest will be the detailed list of
WinHelp 4.0 enhancements at the end of the message.

DISCLAIMER: This report represents our human, sadly fallible impressions and
understanding of the conference.  It is not an authorized or official
summary, neither do we claim that it is technically accurate.  Opinions
expressed are ours alone; and the content is in no way endorsed by our
company.

Trevor Grayling
Frank Ripp
MDL Information Systems, Inc.



                            EXECUTIVE SUMMARY
                            -----------------

The 3-day conference covered four main areas:

* Additional functionality in online help for Windows '95
* Writing & Design for Windows online help
* Online-Help Project Management
* Technical information

It is clear that Microsoft has made a major investment in improving Windows
online help.  There is a substantial list of new functionality for Windows
'95.  Of particular interest:

* Closer integration of online help with the user interface via "shortcuts."
* Table of Contents and Index can span multiple help files
* Easier linking between multiple help files
* Ability to print multiple help topics
* Improved dialog-box help
* Cut-and-paste of help text to end-user's word processor


CONTENTS OF THIS MESSAGE: A summary of the courses provided, followed by a
detailed list of WinHelp enhancements.




                             INTRODUCTION
                             ------------

DEFINITIONS

* Windows '95: The next release of Microsoft Windows.
* WinHelp: Online help created with any version of Microsoft's help compiler.
* WinHelp 4.0: Online help for Windows '95, created with version 4.0 of the
Microsoft help compiler.



EXPLOSION OF INTEREST IN WINHELP

Last year's conference was attended by 35 users.  This year, there were 225
attendees from 25 states, 3 Canadian provinces, the UK, and Israel.  In
addition, 100 were turned away for lack of space.  Help-authoring tools were
displayed by 12 vendors.  Over 12,000 copies of "Developing Online Help for
Windows" by Boggan, Farkas, and Welinske have been sold to date.



WINHELP AS THE TOOL OF CHOICE IN ONLINE PUBLISHING

Only 50% or so of the attendees create help for Windows applications!  The
other 50% use WinHelp for the online publishing of company policy & procedure
manuals, employee handbooks, product specifications, directories, product
catalogs, open positions, information for Sales/Marketing staff, and so on.
We were told that the specifications for the Boeing 757 were created and
distributed with WinHelp.





                             CONFERENCE COURSES
                             ------------------

The following information is provided in an "overview" format. The titles and
brief summaries should provide the scope and coverage of the conference.



ACCESSING MULTIPLE HELP FILES  (Course 103/104)

A major issue is the proliferation of help files.  WinHelp 4.0 provides
significant relief in this area:

* COMPREHENSIVE TABLE OF CONTENTS: The expandable Table of Contents can
include any help files.

* COMPREHENSIVE INDEX: Similarly, the Index can include entries from any help
files. Provision is made for identifying overlapping issues, such as:

database, opening (Application #1)
          opening (Application #2)

Close adherence to style for ToC and index entries will be required if
the above two features are to work successfully.

* HYPERLINKS BETWEEN HELP FILES: Hyperlinks can access other help files
without needing an identifying context string.

Additional Technical Information:

- Can display a dialog box listing "Related" topics that come from multiple
  .HLP files. "Related" topics contain the same keyword (index) entry.
  Implemented using "KLink" macros.
- Can display a dialog box listing "Associated" topics from multiple
  .HLP files. "Associated" topics contain a specific footnote that
  you define (which users never see). Implemented using "ALink" macros.
- Can specify your own error message if WinHelp looks for associated links
  and none exist.





PUBLISHING WITH WINHELP (Course 502)

This course provided an overview of:

* The pros and cons of online publishing versus paper
* Benefits of using WinHelp over other online-publishing products
* Limitations of WinHelp for the online publisher




WINHELP PROJECT MANAGEMENT (Course 503)

This course discussed several major topics in WinHelp project management:

* UPFRONT PLANNING: Design documents; time estimates; resource requirements.
* PROTOTYPING: Creating an online prototype that is a representative subset
of the completed project, using the tools and processes you plan to use for
the real project.
* USABILITY TESTING: Testing the prototype on representative users.
* WRITING: Write the details as late as possible, test against application.
* SCHEDULING: Establish priorities in case items need to be dropped.
* TESTING: Testing everything in the HLP file.





LARGE-SCALE HELP PRODUCTION (Course 601)

This course discussed large-scale projects with many source files and many
writers. It emphasized upfront planning:

* Design overall structure of the help system (hierarchy)
* File-naming conventions
* Format/Style conventions
* Help-page design specifications
* Assign authors to specific files
* Develop a version-control system
* Investigate and test authoring tools

The next edition of Jack DeLand's book, "Mastering WinHelp", will contain
numberous macros for maintaining large numbers of source files.




ADVANCED WRITING & DESIGN (Course 504)

The presenter, David Farkas, University of Washington, concentrated on:

* The components of procedure topics (user tasks)
* Why online help frustrates or fails the end user
* New directions in help design: Minimalism, Hide-the-Details Help, Wizards.




WINHELP 4.0 DESIGN (Course 102)

This course covered:

* DIALOG-BOX HELP: User-interface annotations, or "balloons," for dialog
boxes are integral to WinHelp 4.0: Any part of a dialog box can be associated
with a balloon.  Because these balloons are in fact WinHelp pop-ups, they can
contain direct hyperlinks to help screens for additional information.
* SHORTCUTS FROM HELP TO THE UI: Procedures in a help file can contain
hyperlinks or buttons that are direct shortcuts to UI features.  For example,
if a procedure states that a specific dialog box needs to be open, the user
can click a hyperlink or button in the help screen to bring up the real
dialog box.
* SECONDARY WINDOWS: The increased functionality available in secondary
windows, the ability to define 255 different windows, and the ability to have
9 open at one time, offers more scope in online-help design.  Microsoft likes
to use these for procedures because: (a) the window will auto-size to fit the
text; and (b) overview or background help can be dismissed, leaving a (small)
procedure which will overlay the application less.




THIRD-PARTY TOOL DEVELOPMENT (--)

Twelve vendors displayed tools to develop WinHelp files.  In addition, 20
shareware vendors displayed utilities.

Blue Sky (RoboHelp) announced support for multimedia (sound, animation,
full-motion video) in version 3.0, available now.

Altura (QuickHelp) announced support for WinHelp 4.0 functionality in
"QuickHelp '95," due in June '95.




WINHELP 3.1: TIPS AND TECHNIQUES (Course 202)

Course included various tips on the following topics:

- Creating/customizing hot spots.
- Handling smart quotes and other characters.
- Cropping, bleeding, and layering bitmaps.
- Creating and managing secondary windows.
- Adding buttons and keyboard accelerator.




WORKING WITH GRAPHICS (Course 201)

Course covered many tips and techniques for working with graphics in WinHelp
3.1, including the following (not in the course notes):

- VISIO and Borland Resource Editor recommended as good bitmap editors.
- PAINTBRUSH always creates/displays bitmaps at 96 DPI, no matter what the
  screen resolution is.
- "Large Font" video driver issue: 95% of users use Small Fonts, so create
  graphics using Small Fonts driver setting.
- Do any bitmap scaling in a screen capture program whenever possible.
- Don't scale metafiles more than 75% - they tend to distort.
- If you use metafiles, use only the standard fonts included with Windows.
- Use the Excel dialog editor to easily create bitmapped buttons.




INTRODUCTION TO CONTEXT-SENSITIVE HELP (Course 402)

Course covered the basics of how to add context-sensitive help to an
application.

- Most applications still don't have context-sensitive help due to cost.
- The chapter on context-sensitive help in the Doc-To-Help manual is highly
  recommended as the "best" explanation of the topic.





               WINHELP 4.0 - NEW FEATURES/ENHANCEMENTS
               ---------------------------------------

Notes: (1) If you compile a help file using WinHelp 4.0 AND use the new
features, the .HLP will NOT run under Windows 3.1. (2) You can set a switch
in the WinHelp 4.0 compiler to compile 3.1 help files that do NOT use any new
features - these .HLP files WILL run under Windows 3.1. (3) WinHelp 4.0 WILL
run existing, unmodified WinHelp 3.1 help files.


CONTENTS TAB /WINDOWS HELP DIALOG BOX (Course 103/104)

- Dialog appears when users first open a help file OR when they click the
  Contents button on the help toolbar.
- Sections are represented as books, individual topics as pages.
- User clicks on a book to see the pages underneath, or clicks a page to
access
  a topic. The user's view can be expanded/collapsed, like in an outliner.
- Can include sections/pages from multiple .HLP files.
- Can have up to 9 TOC levels.
- Implemented using a .CNT file which MUST be shipped with the .HLP file.



INDEX TAB /WINDOWS HELP DIALOG BOX (Course 103/104)

- Replaces current "Search" dialog.
- Can create a 2-level index (primary entry with any number of secondary
  entries.)
- Can include keyword (index) entries from multiple .HLP files.
- User can specify the .HLP file whose index entries they want to view.
- "Show Topics" area is gone. If an index entry has 2 or more hits, a
  dialog box appears where the user chooses which topic to view.
- Can specify that a topic accessed from the Index tab is displayed in a
  secondary window.
- Implemented using a .CNT file which MUST be shipped with the .HLP file.



FIND TAB /WINDOWS HELP DIALOG BOX (Course 103/104)

Microsoft has created an extensive full-text search capability for WinHelp
4.0.  The user can search for unique words, word combinations, word
fragments, and so on.  Find develops and displays a list of help topics that
contain the word hits.  It can also find "similar" topics if these have been
indexed as such by the author.  Extensive support is built in for many
languages, including Japanese.

The presenter pointed out that this feature is useful where
WinHelp is used in an online-publishing role, but that it may not be useful
in an online-help role where the information is structured in a hierarchy and
may make sense in particular contexts only.  For this reason, help developers
can exclude specific HLP files from being searched and can even remove the
Find feature altogether from their online help.



AUTHORABLE BUTTONS (Course 103/104)

- Can create real Win95-style buttons that depress when clicked without
  having to create bitmaps.
- Can specify button text.
- Buttons execute one more macros.
- Compiler automatically assigns key accelerators to these buttons.



SECONDARY WINDOW ENHANCEMENTS (Course 103/104)

- Can add all the standard help buttons to a secondary window.
- Can use right mouse button to access help functionality.
- Can define up to 255 different secondary windows (up from 5).
- Can have up to 9 secondary windows open at the same time (up from 1).
- Can specify that a secondary window is "auto-sized" so that it is only as
  large as the text it displays.
- Can have a "Back" button in a secondary window (but it only takes you back
  within that window.)
- Can specify that an index or find entry jump is displayed in a secondary
  window.


GRAPHICS SUPPORT ENHANCEMENTS (Course 103/104)

- Supports 16 color, 256 color, and 24-bit (million) color bitmaps without
  any extra work.
- Includes built-in bitmaps for things like bullets, em dashes, and so on.
- Can have "transparent" bitmaps where the background color "shines" through
  a white background.
- Can change the color of a pop-up window.
- Supports the WingDing font.



PRINTING ENHANCEMENTS (Course 103/104)

- User can print a range of topics by selecting a book or a page from the
  Contents tab.  Each topic begins a new page.
- User can print pop-up windows by using the right mouse button.
- New macros give authors total printing control - can print any
  range of topics in any order.



"SHORT CUTS" (Course 102)

- Author can display a specific dialog from any application.
- Author can display a specific file in any application.
- Implemented as a macro; can be triggered by clicking a button or hot spot.
- Requires author to hard-code programmer's dialog ID.
- Used in Microsoft's help for Windows 95.



INTERFACE POP-UPS (Course 102)

- Balloon help for dialog boxes done right: User moves mouse over dialog box
  element, presses right mouse button, selects "What's that" and sees a
  description.
- Uses topics from .HLP files; these topics can contain links to other
topics.



ADDITIONAL HELP USER INTERFACE CHANGES (Course 103/104, 106)

- Can specify a "help family." This determines which .HLP files are included
  in the Contents and Index tabs. Author specifies the default "help family."
  But the end-user can add or delete help files to the family.
- Can directly select and copy text (but not graphics) from a help screen.
- Can access most help functionality by pressing the right mouse button.
- Can copy and print pop-up windows using right mouse button.
- Can change font size (small, regular, large) using the Options menu. Author
  defines what "normal" is.



AUTHORING/COMPILER IMPROVEMENTS AND CHANGES (Course 103/104)

- New WinHelp 4.0 compiler (HCRTF.EXE) is now a Windows application.
- Compiler includes editors for .HPJ and .CNT (contents) files.
- Can compile existing WinHelp 3.1 projects.
- In debugging mode, can include topic numbers in a topic's title bar.
- Can print out a list of keyword entries from ANY .HLP file, including
  other people's. This lets the author create KLinks to specify "Related"
  topics.
- New error message specifies which bitmap WinHelp couldn't find when
  compiling.
- "Much faster" compilation.
- Term "context string" changed to "Topic ID."



MACROS (Course 301)

- 26 new macros were added to support new WinHelp 4.0 functionality.



MICROSOFT'S STYLE AND DESIGN FOR WINDOWS '95 HELP (Course 106)

Much of the documentation for using Windows 95 is online only. Some basic
information appears in a 100-page User's Guide.

- No separate glossary.
- No tutorials.
- No "advanced" information included.
- All procedures displayed in secondary windows that are "auto-sized."
  Microsoft is apparently not using the Main window.
- Procedures are task-oriented, written in minimalist style, and do not
  contain overview material.
- Procedures for less-often used functions rely on shortcuts. Such a
  procedure might include a step that reads "Click" followed by an icon.
  The user clicks the icon, and the actual dialog box appears. Or, the user
  clicks the icon, and a Wizard appears - for example, the "Printer Setup"
  procedure.
- Win95 creates a \WINDOWS\HELP directory where Microsoft puts all of their
  help files. They "recommend" that developers put all their .HLP and .CNT
  files there.