(Draft in progress below ... not completed)


The main purpose behind this requirement is to support a good user experience, with task-specific help content that is delivered electronically in the context of doing tasks within Kuali software, so the user does not have to navigate separately to find relevant help content.

In order to achieve this, we need to support a help information architecture that makes it easy to create, update, maintain, translate and link high-quality help content with the logic/codebase.  

Detailed Description


Ideally, the user interface to the application itself should be designed in such a way that it does not require a large amount of collateral information.  We caution against making the user feel lost in too much information.  This is not aimed to be full conceptual information about the application's architecture, rather, is aimed to be task-specific help. 

The main requirement is to support a good user experience with online help, with task-specific content that is delivered electronically in the context of doing tasks within Kuali software, so the user does not have to navigate separately to find relevant help content.

Note that this represents a step towards, but is not the same thing as full convergence that unifies all help and electronic documentation.


Usage Scenarios

These are coming next!

Mocks and Diagrams

For context, in this section we cover

For context, what "help" is already supported

Already Supported in KNS:

To date, Kuali applications haven't typically provided field-level, section-level, or page-level context-sensitive help.  But Kuali applications today, such as Kuali Financial System and Kuali Coeus, do provide help for some documents, at the document level.  For example, see below from the KFS Test Drive (login as admin):

When the user activates the document-level help icon in KFS, another browser tab opens with the "stand-alone" electronic documentation opened to the appropriate place within the larger information content.  Therefore, KFS has achieved context-sensitivity in their document-level help model, a significant step forward.

In Kuali Coeus , when the user activates the document-level help icon, another browser tab opens, just as it does in KFS.   Not all documents have help, but for those related to lookups, the following type of help information is displayed in the separate browser tab.  This example comes from the KC Test Drive (login as admin):

There are pros and cons to each of these approaches.  The KC approach doesn't carry the risk of leading the user into other information foraging activities, that are not related to the immediate task at hand.  But, unlike the KFS approach, it also doesn't support the users who don't find what they feel they need, within this more "bounded" and generic lookup help information window. 

Today, the KFS and KC online help authors complete a spreadsheet that identifies the URL for each help topic (the name of the top-level html file for each doctype), and delivers the spreadsheet along with a single zip file that contains the html files, to the application's development team.  The developers then insert the appropriate URL into the places in the code-base to be the action triggered upon the users' selecting a help icon. 

See the following code snippet from the preceding KFS example.   The URL tells the application where the help content is located and which topic is the anchor point to open to ("INVW" in this example).

<div id="headerarea" class="headerarea">
     Customer Invoice Writeoff&nbsp;
      <a title="[Help]document help" target="helpWindow" tabindex="-1"
           <img hspace="5" border="0" align="middle"
            alt="[Help]document help" src="http://testdrive.kfs.kuali.org/
<div class="headerbox">

Though a context-sensitive help structure is possible, prior to Rice 2.2 KRAD, linking appropriate help content at the field or section-level via a help icon, for context-sensitive help, is not done in most Kuali applications today.  It may be perceived as significant additional work to accomplish through the method described above, and/or may be perceived as not needed for the target audience.

What is already supported in Rice 2.0 KRAD:

KRAD in Rice 2.0 supports including visible text anywhere on a page.  This enables an application to include short explanatory text at the top of a form or at the beginning of a section -- virtually anywhere in the view, where visible explanatory text is needed and appropriate.

In Rice 2.0, KRAD also makes it easy to associate "visible" instructional text and constraint text with input fields.  The input field itself can include a watermark "suggestion" or it can be pre-filled with a valid default selection alternative, that the user can accept or change.  The field can include auto-complete behavior (recognition/type-ahead).

The input field is grouped with a label, which can include a "required-ness" indicator (the *).  As with the KNS capability, the input field can have other controls associated with it, such as a lookup or inquiry control, and could have multiples of these.  It can also include a drop-down control that enables the user to select from a valid set of alternatives (not shown).

All these are optional, but available to the application designer.

In addition, as with KNS, a help icon can be placed in the view, for example to provide document or view-level, or page-level, section or sub-section level, or field-level help.  However, if there are many field-level help icons throughout a densely constructed page, this could lead to visual clutter, making  it more difficult for the user.  And it could be especially problematic if a help icon is added to a field that already has a lookup or inquiry icon (or both!). 

What "help" constructs will be new in Rice 2.2, KRAD:

There is a new UI construct related to help architecture in Rice 2.2 KRAD, and a data structure addition to make it easier to hook the appropriate help content into the appropriate place in the UI when developing an application.

Diagram of the relationships among help constructs: 

The diagram above shows how the new help framework can support the KNS model, in addition to extending it to support the rich UI needs for student-facing applications and for administrative functions that can't incur a steep learning curve for infrequently performed tasks.  In this model:

Note that there is no technical obstacle to providing the simple or complex tooltip for any level of the help, though there will be a size constraint (you do not want to have a very large tooltip, too much content).  There is also no technical obstacle to providing the icon and separate browser window for any level of help, though having another window open for very brief field-level help isn't recommended (and there may be no room to place a help icon). 

These are application-level decisions.  The page-level help content structure itself is also up to the application.  Rice 2.2 KRAD, as a middleware platform, aims to be agnostic with respect to the Content Management System chosen by the application or university system, rather than to require a specific CMS.  KRAD will include default templates for configuring URLs with system parameters, so that applications can link into their application help content from the appropriate points in the application, to the appropriate anchor points in the help content.  (We will work with the Kuali applications to provide a good reference platform / model for other applications and teams coming new to Rice.)

The two Tooltip modes:

Research has shown that users often don't notice helpful text on a densely laid-out page, so the tooltip strategy for field-level and section-level help offers the application designer a "just-in-time" help capability.

There will be no help icon in the UI to signal that there is a tooltip associated with an element.  But tooltips have become standard fare in rich applications, and users now actively explore user interfaces looking for these relevant 'nuggets' of information (tooltips and other) when they use a new application or infrequently use it. 

The "simple" Help Tooltip for controls and fields:

The "simple" help tooltip enables applications to deliver context-sensitive help for individual fields and controls, virtually, for any user-manipulable control - without cluttering the page.  The tooltip appears on hover (and on focus for keyboard users) and disappears when the user moves on.  The content is concise, styled text.

The richer "complex" Help Tooltip for section-level help:

The "complex" help tooltip supports links and buttons that the user can interact with, for example, to link to additional information if needed.  As with the simple tooltip, the complex tooltip appears on hover (and on focus for keyboard users) and disappears when the user moves outside of the contiguous area formed by the trigger element and the tooltip content itself.  If also closes if the user activates a link contained within the tooltip content.

See the tooltip requirement for additional information and details on the tooltip construct.


If applicable, list expectations for performance (optimal and worst cases would be fine, give time in seconds):


See the tooltip requirement for additional reference information and details.

Requirements Listing

The Help Framework consists of the following:

1. Tooltip:

The below is a high-level overview only.  For more details, see the separate tooltip requirement.

  1. The tooltip is the UI component that delivers context-sensitive help for fields and other user-manipulable controls.
  2. When the user hovers over a user-manipulable element (e.g., a field or other control in a form), brief help summary text for the specific field/control should be displayed as a tooltip. 
  3. The tooltip should remain open while the control or field is selected, including while the user is entering data into a field.
  4. The tooltip will close when the user moves out of the field.
2. Help Window associated with the Help icon/button:
  1. KRAD should enable displaying a help icon associated with any element, for example, with a document header, view and page header. The default placement of this help icon will be to the right of its associated UI element.  (Precise default visual treatment and positioning to be determined.) 
    1. The KRAD code structure will group this icon appropriately with its element (i.e., fieldset/legend semantics in the code structure will enable assistive technologies to convey that this help icon is for its associated element).
  2. KRAD should ship with a default help icon (precise default visual treatment to be determined), with default alt-text for it.  (Research whether the alt-text can include a variable that enables it to be pre-filled with the associated element's label.) 
    1. Secondary:  KRAD should also allow the ability, at a global level (per application, not per view or page), to replace the default help icon with a different image or with text.  Consistency across an application is important.
  3. When the user hovers over the help icon, brief summary text should be displayed as a tooltip for the help icon.  This doesn't include the help content itself, but a brief description of the type of help that selecting the help icon will produce.  Examples:  "Display help for this page". (Research whether the help icon's tooltip content can include a variable that enables it to be pre-filled with the associated element's label or its alt-text.)
  4. The Help icon should be selectable and, when selected, should open the help information in a new browser window (not new browser tab):
    1. The new browser window should be sized and placed by default, and appear above the application window in the z-order (not be occluded by the application window upon opening).  The user can move and resize the new browser window, as appropriate to the needs. The opened browser window appears in the operating system's open applications bar (standard behavior), helping the user to locate it if, in the user doing other things, it gets hidden by the application or other open windows.
    2. Applications should be able to configure a URL with system parameters, for example, to link the help icon with where the help content is stored and to name an anchor point within the help content.


List any functional or technical work that must be completed before work on this item can begin:

  1. (This is listed in the tooltip requirement, which is a dependency in this overall help framework:  Assess & select which jQuery or other tooltip plug-in to use.)
  2. Research whether there is a way to automatically pre-check for the amount of content being put into a rich tooltip, to shift it instead into the separate browser window if the content exceeds the recommended limit.  (The user experience will not be great if a tooltip is very large.)
  3. Research whether the two choices described above -- the rich "complex" tooltip and the separate browser window, opened by default and sized/positioned appropriately -- satisfies the user experience objectives or if we need to put back in a 2nd help construct, which is a non-modal help dialog that is tightly aligned with the application window and is above it in the z-order (will not be occluded/behind the application window), that can be moved aside and outside of the application window by the user in order to view side-by-side and maximize the view, and that can be closed by the user when no longer needed.
  4. Research the usefulness of associating a help icon to signal that there is a tooltip associated with an element (pros and cons). (Cons: this is not standard / typical -- Isn't typical in tooltips for controls, would take up too much space for elements in table cells, and be visual clutter for pages with many fields with field-level tooltips.  Pros: there may be some elements that already have other triggers associated with them, so could not also have an associated tooltip unless we associate a different target element with it.)
  5. Research whether the alt-text for a help icon can include a variable that enables it to be pre-filled with the associated element's label.
  6. Research whether the help icon's tooltip content can include a variable that enables it to be pre-filled with the associated element's label or its alt-text.


List any issues that need to be resolved before work on this item can begin:


QA or Regression Testing Plan

List steps needed to test the basic functionality of this update, enhancement, bug fix

  1. test/steps
  2. test/steps


Functional Analysis Complete? No (completed by SME)

Needs Review by KAI? Yes

Technical Analysis Complete? No (completed by DM)

Needs Review by KTI? No (completed by DM)

Estimate: 30 hours (completed by DM)

Technical Design: Link Here (completed by DM)

Jira: KULRICE-6674

Final Documentation: Link Here (completed by DM