(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.
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.
These are coming next!
For context, in this section we cover
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"> <h1> Customer Invoice Writeoff <a title="[Help]document help" target="helpWindow" tabindex="-1" href="http://testdrive.kfs.kuali.org/kfs-ptd/kr/ help.do?methodToCall=getDocumentHelpText&documentTypeName=INVW"> <img hspace="5" border="0" align="middle" alt="[Help]document help" src="http://testdrive.kfs.kuali.org/ kfs-ptd/kr/static/images/my_cp_inf.gif"> </a> </h1> <div class="headerbox"> </div>
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.
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!).
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.)
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 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 "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.
The Help Framework consists of the following:
The below is a high-level overview only. For more details, see the separate tooltip requirement.
List any functional or technical work that must be completed before work on this item can begin:
List any issues that need to be resolved before work on this item can begin:
List steps needed to test the basic functionality of this update, enhancement, bug fix
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)
Final Documentation: Link Here (completed by DM