Designing a help system for the authoring tool

This is a discussion of PAS-63@issues

<Tony's notes>
The live help tab could be removed

the scenario:

1. a step is selected in the pas customizer card.
2. user clicks help button on toolbar
3. the card flips to the help card
4. on the left side of the card is a list of help topics, general help, and a topic for each step.
5. the step that they where on is highlighted but not selected.
</Tony's notes>

Laurel's thoughts on above...
What about general help? How to get started? How do we envision those fitting in with the scenario described above?
Authoring tool currently begins by requiring user to chose existing curnit or open blank one. Wondering why this is done so differently from other editting tools such
as web page editors, etc. Most editing tools open the editing environment and then give you the options you might want via the menu system, such as open file, create new file, help, etc. One concern I have about the current technique is that there is no help offered at this time (although a tips or getting started option could be added).

Ideas:

Web-based - Provide help online via the wiki and then use browser technology as is currently done with the "live help"

advantages

• this is what we already have, so no additional programming
• interactive, users can add help

disadvantages

• browser technology required (Have there been problems with the webrenderer technologies in the past?)
• network connectivity required

Resources

Oracle help for Java apps

Oracle Help
JavaHelp is the help standard for the Java platform as defined in
JSR-97. OracleHelp is proprietary implementation. JavaHelp does allow
for a native viewer for those that prefer a richer presentation format.
It also allows the user to change the viewer to any other viewer but
this requires additional programming.

Resources

http://www.oracle.com/technology/tech/java/help/index.html

Java based context sensitive help

Java-based - JavaHelp

advantages

• very powerful:
  • JavaHelp Features and Benefits
    • JavaHelp provides several features that are useful for authoring documentation. In addition, there are reusable components that save Java developers lots of time re-inventing the wheel. Some JavaHelp features are:
      • Help Navigators: Table of contents (TOCs) support a collapsible and expandable display of topics, unlimited number of hierarchical levels, and merging of multiple TOCs; an index supporting merging of multiple indexes; and full-text search that is flexible and configurable.
      • Compression: A JavaHelp-based help system can be compressed and encapsulated in a single Java ARchive (JAR) file.
      • Extensible and Customizable: The JavaHelp APIs can be used to customize or extend the user interface and its functionality. Extensions can be custom navigation, or even voice and sound. This gives authors great flexibility and control in designing help systems.
      • Context-Sensitive Help: This is provided through Swing.
      • Merging Capabilities: Multiple help components can be merged before they are presented to the user.
      • Dynamic Updating: Allows an online help system to be dynamically updated after it has been released.
      • Adaptable: It enables help systems to be adaptable in presenting and displaying information. This is especially useful when the final deployment environment is not known ahead of time.
      • Localizable: Java supports internationalization (I18N), and therefore the JavaHelp system can be easily localized into international markets.
  • Deployment and Operating Scenarios
    • JavaHelp technology offers authors and developers several options for deploying or invoking it from within applications. It is network-centric, so that it can be launched independently of the application it supports. It can even be embedded within the application. And since it is written in Java, it is platform- and browser- independent and can run on any platform and browser that supports the Java Runtime Environment (JRE). This makes it ideal for use in today's heterogeneous computing environment.
      • Here are some scenarios where JavaHelp can be deployed to present help information:
      • Standalone applications: This is a local application that runs on the desktop without the need for a browser. The JavaHelp help viewer can be launched as a separate application or one that is embedded within the application itself.
      • Network applications: These are network applications that fetch data from remote servers. It is possible for the JavaHelp system to load its help information from remote servers. This is useful for software vendors so they can provide their customers with a lightweight client application that fetches the help information from remote servers. Vendors can change help information as they wish, without having to ship a new release.
      • Applets: Mini applications that run within a web browser. The JavaHelp system itself can be part of the browser and the help data may or may not be part of the application.
      • Server-based Applications: This is an application that runs on a Java server but uses the browser for its GUI.

• can add help to individual beans, ie. Authored Pas Steps (this can be coupled with the wiki-based help-Turadg)
• no requirement for user to be on network

disadvantages

• user may not be able to add comments to help easily (LW- note actually this may not be true as we may also be able to use the html pages that are part of the help system from a remote location, so could perhaps incorporate wiki pages into the help system - I can experiment with this)
• could also not easily share this help with remote users by recommitting the help files to the main code base.

Resources

• JavaHelp authoring tools, etc.
• JavaHelp article