Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 42 Next »

(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

  • #1: Create a context-sensitive help information architecture, that supports
    • field and object-level help in a "simple" text tooltip
    • section-level help in a richer "complex" tooltip that can be interacted with
    • Page-level help in a separate window or browser tab (opened to specific anchor point that is relevant for that page)
  • #2:  Create an integrate-able help information architecture that makes it easy to create, update, maintain, translate and link high-quality, context-sensitive help content within the logic/codebase:
    • That is separable from the logic/code-base.
    • That makes it easy to programmatically link field, sub-section, section, page, view and document-level help "hooks" into the logic/code-base, to appropriate anchor-points in the help content/architecture.  This could be to anchor points within a single online help structure, to deliver the right information from within the larger information space (see the page-level help model in the material below).   Or, it could be to field and section-level tooltip content pulled from a single resource file or other centralized help construct (related to the requirement for Centralized Message Repository).
  • #3: Enable applications to choose which level(s) of the help content to implement.  For example, one application might need field-level help only, while another needs field-level and section-level help, while another needs field-level and page-level help, and so on.  (We caution, however, against making the user feel lost in too much information.  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.)
  • #4:  Support the integration/use of the html output from any authoring tools that output into standard XML/HTML source -- essentially, support pulling the content from any content management repository selected by the application / university.

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.  This is not aimed to be full conceptual information, rather, is aimed to be task-specific help.  Note that this represents a step towards, but is not the same thing as full convergence that unifies all help and electronic documentation.

  • #5:  Create an online help architecture that fully converges the aspect of online help with the aspect of electronic documentation.
    If this is achieved, it is conceivable that all user help and user documentation could be from the same source - there would be no duplication of effort required to create, update or maintain the content.
    The primary requirement even in #4 is that when accessing task-oriented help (such as field-level, group-level), the potential unity with all user help information is achieved in a way that does not lead the user to become lost within a larger online documentation structure.  See the usage scenarios, and the mocks and diagrams sections above (these are coming).
    This type of converged overall help/documentation structure must support the following:
    • table of contents - Accordion-style expandable table of contents in left sidebar
    • help index - Alphabetical index
    • help search - Great search capability with highlighted hits
    • help glossary
    • hyper-linked cross-references within and across the help content and these constructs.
    • The information in this converged overall form must be printable, with pagination cues (page numbers printed).
    • Ability to save help topics to Favorites for infrequent tasks
    • Feedback e-mail capability

Usage Scenarios

These are coming next!

Mocks and Diagrams

First, for context, we cover what is already supported in KRAD, which is new in Rice 2.0, and what is supported in KNS, and then we move on to cover the new upcoming functionality.

For context, what "help" is already supported

In Rice 2.0 KRAD:

Below is a low-fidelity sketch of the types of visible 'help' associated with input fields, that are available in the new Rice 2.0 KRAD (a significant addition to the KNS capability) -- optional, depending on the application, device and user needs.

Differently from KNS, KRAD makes it easy to associate "visible" instructional text and constraint text with input fields.  The input field itself can also 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 a combobox drop-down control that enables the user to select from a valid set of alternatives (not shown), and it can have auto-complete behavior (recognition/type-ahead).

The input field is grouped with a label, which can include a "required-ness" indicator (the *).  This is similar to KNS and, as with the KNS capability, the input field can have other controls associated with it, such as a lookup or inquiry control (shown above with an icon to the right of the field), and could have multiples of these (could also include a help icon).

In addition to the above constructs, KRAD in Rice 2.0 also supports including visible text anywhere on a page.  For example, this enables an application to include short explanatory text at the top of a form or at the beginning of a section -- virtually anywhere on the page where the text is needed and appropriate.

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

In addition, as with KNS, a help icon can be placed on a page, for example to provide page-level help, or section-level help, or field-level help.  However, if there were to be 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!). 

Though this context-sensitive help structure is possible, prior to Rice 2.2, there is no packaged support to make it easy for application developers to tie appropriate help content at the field or section-level, for context-sensitive help.  It could be done, but most Kuali applications do not do this today, due to the additional work it takes to accomplish.

Already Supported in prior KNS (& Rice 2.0 KRAD):

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

When the user activates the page-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 page-level help model, a significant step forward.

In Kuali Coeus , when the user activates the page-level help icon, another browser tab opens, just as it does in KFS.   Not all pages 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" help information window. 

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

There are two new UI constructs 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:

This diagram above shows how the new help framework can support and extend both the KFS and KC current models, in addition to supporting the rich UI needs for student-facing applications and administrative functions that can't incur a steep learning curve for infrequently performed tasks.  In this model:

  • Field-level help can be provided in a "simple" text tooltip. 
  • Section-level help (which may or may not be composed of the field-level help with some prefatory context information) can be provided in a richer "complex" tooltip, that can be interacted with.   
    • Note that this may be the same tooltip construct running in a richer "complex" mode - technical analysis is underway.
    • Note that this could include a link to an anchor point in the larger world of information to the full application-level documentation. 
  • Page-level help can be provided in a separate window or browser tab. (Technical and user analysis is underway on the capability to open a new browser window & to optimize the default opening-window size,  rather than opening a new browser tab, to more easily enable side-by-side viewing.)

The page-level help content structure itself is 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.

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.  There will be no help icon in the UI to signal that there is a tooltip associated with an element.  But

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 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.


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


Include links to other confluence pages or external resources that might be helpful for this issue:

Requirements Listing

The Help Framework consists of the following:

1. Tooltip:
  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.

For additional tooltip architecture details, see the separate requirement on tooltips.

2. Help Window associated with Help icon/button:
  1. System should allow displaying a help icon associated with a page header (also possible to do with a section 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. Secondary:  System should allow turning this type of help information off at a global level (per application) (Let's talk through the typical scenario for this - why this is desired.)
    2. Tertiary:  System should allow turning these off also at a view level, and component level (NOTE:  Not sure yet about this one, will walk through  - scenarios to determine the pros and cons of enabling this. Creates inconsistency across an application.)
  2. KRAD should ship with a default help icon (precise default visual treatment to be determined), with default alt-text for it. 
    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:  "Select to display help for this page"
  4. The Help icon should be selectable and, when selected, should open the help information in a new browser window.  Applications should be able to configure the passed URL with system parameters, for example, where the help content is stored and naming 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. item


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

  1. item
  2. item
  1. item
  2. item

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 (completed by SME)

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)

  • No labels