ui best practices

UI Best Practices for Products Built on Tivolis Process Automation Engine

Document version 1.0

Copyright International Business Machines Corporation 2011. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.


CONTENTS

Revision History ................................................................................................................ v

1 Overview................................................................................................................1

2 Screen Layout .......................................................................................................1

2.1 Default screen layout .................................................................................1

2.2 Field repetition across tabs........................................................................2

2.3 List tab organization...................................................................................2

2.4 Sections containing related fields ..............................................................3

2.5 Order of tabs in an application...................................................................3

2.6 Visible rows in a default table window .......................................................4

2.7 Display of entire dialog or popup window ..................................................5

3 Style and Details....................................................................................................6

3.1 Capitalization in tabs, labels, and other GUI text.......................................6

3.2 Abbreviations .............................................................................................6

3.3 Default data in fields ..................................................................................7

3.4 Section titles ..............................................................................................7

3.5 Fields that reference other applications.....................................................8

iii

iv

3.6 Entry fields for SQL expressions ...............................................................9

3.7 Color to emphasize important labels .......................................................10

4 Accessibility .........................................................................................................11

4.1 Alt-text for hyperlinks, images, and icons ................................................11

4.2 Keyboard use for all interactions .............................................................11

4.3 Color to enhance, not convey, information ..............................................11

4.4 Pictorial representations to enhance, not convey, meaning ....................12

5 Reference............................................................................................................12


REVISION HISTORY

Date Version Revised By Comments

March 11, 2011 1.0 DB

v


1 Overview This document is intended for developers, internal and external support teams, and others who are configuring the user interface of a product built on Tivolis process automation engine.

The products for which the UIs are most often configured are IBM Tivoli Service Request Manager, Tivoli Asset Management for IT, and IBM Tivoli Change and Configuration Management Database. Customers frequently want to implement these products in a way that meets their unique business needs. The UI might be laid out differently, fields might be added or deleted, and so forth. Following the best practices provided in this document ensures that the UI remains consistent, accessible, and easy to navigate and use.

This document describes the screen layout features, UI style and details, and accessibility features that result in an optimally usable product UI. The document is not intended to provide detailed instructions for how to achieve these UI features. For those detailed instructions, see the IBM Maximo Asset Management 7.1 Application Developer Guide, which you can access here:

http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/index.jsp?topic=/com.ibm.mam.doc_7.1/mam_welcome.htm

Most of the information that pertains to the features described in this document is provided in Chapter 3 of the Application Developer Guide, Common Application Developer Tasks. Where the information is not found in Chapter 3, this document indicates alternative chapters or provides brief instructions.

2 Screen Layout

2.1 Default screen layout The default screen layout requires neither vertical nor horizontal scrolling when the page is viewed in English at a screen resolution of 1024x768. Example applications: Changes, Service Requests, Assets The typical screen in a product built on Tivolis process automation engine has a default layout that requires no scrolling when viewed for the first time, before a user takes any action. This includes any tab, or screen, whether part of a standard multi-tab application, single-page application, or self-service application. When a screens scrolls, users cannot see the tabs; consequently, they can lose the context of what they are working on. Consider keeping some of the infrequently used sections on the page minimized by default, or moving some information to other tabs to keep the screen from scrolling in its initial state. Horizontal scrolling is never acceptable on any product screen.

1

2.2 Field repetition across tabs The most important fields are repeated across all the tabs in the application, except the List tab. Example applications: Assets, Purchase Requisitions, Incidents, Changes The most important or relevant fields in a multi-tab application should be repeated at the top of each tab, in the same location. For example, in the Purchase Requisitions application, the PR number, description, site, status and cost are repeated at the top of each of the four non-List tabs in the application.

In the assets application, the Asset ID, Description and Site fields are repeated across the top of each tab in the application.

2.3 List tab organization The List tab is organized so that Record Name and Description are the left-most columns, Bookmarks is the right-most column, and the most important fields for searching are included in between. Examples: From the Locations application: Location, Description, Type, Status, Priority, Site From the SLA application: SLA, Description, Applies To, Type, Service Group, Service, Status The record name or number is always the left-most field, followed by description. Include status, for something that can have a status and that has only one status at a time. In addition, include fields that are most likely to be needed by users for filtering their data set. The right-most column is always reserved for bookmarks.

2


2.4 Sections containing related fields Related fields are grouped together in sections that users can minimize if the fields are not relevant to their current work. Examples: Note how vendor data is grouped together in one section in Assets, Purchase Requisitions and Purchase Orders; Asset fields always offer the same detail menu options. When creating screen layouts, put the most prevalent, important, or frequently used information at the top of the form (see Section 1.2, Repeating important fields). Then, segment the like fields together down throughout the form, grouped into sections that the user can minimize if they are irrelevant or unneeded. Users who see the same field in different applications should be able to predict based on prior usage in other applications what other, related fields will surround that field and what menu options will be available with it. In addition, a conditional UI can be created in which certain fields are visible to certain user groups and hidden from other groups. Conditional UI features give the UI the flexibility to support different work groups or different work processes. For information about creating conditional UI features, see Chapter 5 of the Application Developer Guide.

2.5 Order of tabs in an application The order of the tabs in an application makes sense based on user tasks, so that users do not have to switch back and forth among tabs to enter standard information. Example: Service Requests organizes the tab chronologically: Service Request, Related Records, Solution Details, Log, Service Address, Specification Another option is to put more frequently used tabs first and less commonly used tabs last. Certain tabs usually appear last, if they appear at all: Service Requests and other applications put their Specification tabs last.

3

2.6 Visible rows in a default table window Rows that are visible by default in a table window include only the most important information. All other information appears in the details view that users can see if necessary. It is difficult to scan information quickly when there is a lot of information to scan. Make it easier to find relevant data by minimizing the amount that appears in table windows. Example: The Meters tab in the Assets application has a table window that shows very little by default, but can be expanded to show a lot of information:

Table rows shown by default Additional information shown only when the little triangle is clicked to reveal details.

4


2.7 Display of entire dialog or popup window When a dialog or popup is displayed on the screen, it appears in its entirety, without the user having to resize or reposition it in order to see the whole thing on a screen set to 1024x768 resolution in a browser that is maximized. Example: The More Search Fields dialog (under Advanced Search drop down) in the Job Plans application. Note how the window fits comfortably on the screen and appears centered in the browser by default:

Dialogs that do not meet this guideline should be redesigned with, for example, multiple tabs or sections closed by default, so that the dialog will be smaller.

5

3 Style and Details

3.1 Capitalization in tabs, labels, and other GUI text Tabs, field labels, section titles, buttons, Action menu items, and detail menu options use title-style capitalization (first letter of each word is capitalized). Help grid text in dialogs uses sentence-style capitalization (first letter of first word only is capitalized). Note how, in the dialog shown below, the dialog title and field labels all correctly use title-style capitalization. The help grid text at the top of the dialog correctly uses sentence-style capitalization:

3.2 Abbreviations Abbreviations are appropriate, but not required, in applications that have the full name used as the application title, and where it would take up too much space to use that full name elsewhere on the screen. Examples: Purchase Requisitions, Purchase Orders The full name, Purchase Requisitions, is spelled out in the application name, and in the upper-left corner of the page when the application is selected, but elsewhere on the screen in tab titles, section headings, and field labels, the abbreviation PR is used to maximize available screen real estate.

6


In general, it is best not to use abbreviations to avoid confusion and translation difficulties, but, if you must use one, include the non-abbreviated form of the word in the associated field help (alt+F1 on the selected field).

3.3 Default data in fields Default data is displayed in any field where information could be anticipated. Examples: Requested By, Entered By, and Enter Date are automatically filled in for new records. In addition, data entered by a user in the Service Requests application is automatically propogated to the Incidents application. If the information could be provided automatically, there is no reason to force a user to enter it; forcing the user to enter the data wastes user time, and risks the user making an entry error. Fill in the field by default and allow the user to edit it, if appropriate.

3.4 Section titles Sections have titles that are brief but meaningful. Example: The Changes application presents multiple sections on the main tab, but each is distinguished by a distinct title that accurately describes the contents of that section. Avoid redundancy, make sure each section has a unique title, and make the title descriptive enough so that users can anticipate what they will find in the section, even when the section is minimized. For example, Service Request Details is more descriptive than Details. Avoid section titles that are the same as the title of the tab where the section is located.

7

3.5 Fields that reference other applications Fields that reference other applications have attached lookup options. Examples: In the PO application, if there is a contract reference. The user can use the lookup menu to go to either Purchase Contracts or Rental/Lease Contracts, whichever is appropriate for the situation.

In the situation above, the lookup offers the user the choice to Go To Purchase Contracts. The following lookup menu is displayed if the field is empty:

Provide all of the Go To options that are appropriate, and provide them in any situation where a user might want to reference another application for the information necessary to fill in the field. Also, provide Go Tos for read-only fields, because users may want to see the context for where data came from, even if they cannot alter it. Note that when users go to another application from a field, the banner cues them that they are no longer in the originating application. The banner changes color and is displayed as follows.

8


The color is muted, rather than the usual brighter blue, and the Return and Return with Value options are available on the far right. If users have launched into the application from a read-only field, do not show Return with Value. Instead, move Return to the far right.

3.6 Entry fields for SQL expressions When an entry field can take a SQL expression as an entry, the field is large enough to handle a potentially large entry, and the field includes a lookup to the SQL Expression Builder. Example: The Escalations application has such a field on its main tab:

Note that the entry field for Condition is larger than the other fields, and the lookup icon (a small arrow to the right of the field) is displayed. When a user clicks the lookup icon, a dialog containing the SQL Expression Builder is displayed, as shown here:

9

3.7 Color to emphasize important labels Color can be used to draw users attention to important field names and other labels in the UI. There are no examples of the use of color for labels in the current ISM product set. However, the capabilities exist to configure the UI in this way. For example, the following illustration shows how the color red might be used to emphasize the Priority: label in the Service Requests application:

For any UI control with a label property, the labelcss="...." attribute can be added in the presentation.xml file. For example, the following would be used to apply the color red to the Priority label:

10


4 Accessibility

4.1 Alt-text for hyperlinks, images, and icons Hyperlinks, images and icons on the screen have meaningful alt-text associated with them. Alt-text is the text that is displayed, for example, when a user hovers the mouse over an icon. It is essential to include alt-text for accessibility when users are using a screen reader. Alt-text is also helpful to people who may not be familiar with icons and need to mouse over for more information.

4.2 Keyboard use for all interactions Every interaction can be initiated and completed using only the keyboard, without the use of a mouse. Some users may not want to use a mouse because it slows them down; others may not be able to use a mouse. No user should have to use the mouse; all interactions, controls and UI elements must be accessible via the keyboard. Using the tab key on the keyboard, tab through the applications and make sure it is possible to tab through all the fields, in the correct ordergoing down one column in a section, then moving across one column to the right.

4.3 Color to enhance, not convey, information Color is used as a way to enhance information and never as the only way of conveying information. When important information is called out via color, such as showing warning text in red, the color can draw the attention of users and help them focus. Certain users, however, cannot perceive color: they may be color-blind or completely blind, in which case the screen contents are read to them by a screen reader. Therefore, if you use color as a way to enhance meaning, make sure that the color is not the only way you convey that meaning. For example, in the example of red warning text, you could start the phrase with the word Warning, so that the intent of the phrase is clear to all users, whether they can see the text or not. This feature can be provided using only the configuration tools that are available.

11

12

4.4 Pictorial representations to enhance, not convey, meaning Pictorial representations are used as a way to enhance information and never as the only way of conveying information. Blind users typically use screen readers like JAWS to interact with software and web sites. These screen readers literally read the information on the screen and tell the user how to interact with controls. Pictorial representations of information (such as jpgs, gifs or java applets) may convey more information than a screen reader can accurately represent. If you must use those kinds of representations, include other ways for someone to access the same information, such as a text description or a table window that accompanies a java applet.

5 Reference For how-to information that pertains to the UI design features that are described in this document, see the IBM Maximo Asset Management 7.1 Application Developer Guide, which you can access here:

http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/index.jsp?topic=/com.ibm.mam.doc_7.1/mam_welcome.htm

Most of the relevant information is provided in Chapter 3 of the Application Developer Guide, Common Application Developer Tasks.


13

Copyright IBM Corporation 2011 IBM United States of America Produced in the United States of America US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A.

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PAPER AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes may be made periodically to the information herein; these changes may be incorporated in subsequent versions of the paper. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this paper at any time without notice. Any references in this document to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation 4205 South Miami Boulevard Research Triangle Park, NC 27709 U.S.A. All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only. This information is for planning purposes only. The information herein is subject to change before the products described become available. If you are viewing this information softcopy, the photographs and color illustrations may not appear.

14

Trademarks IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. If these and other IBM trademarked terms are marked on their first occurrence in this information with a trademark symbol ( or ), these symbols indicate U.S. registered or common law trademarks owned by IBM at the time this information was published. Such trademarks may also be registered or common law trademarks in other countries. A current list of IBM trademarks is available on the web at "Copyright and trademark information" at http://www.ibm.com/legal/copytrade.shtml.

Other company, product, or service names may be trademarks or service marks of others.

1 Overview2 Screen Layout2.1 Default screen layout2.2 Field repetition across tabs2.3 List tab organization2.4 Sections containing related fields2.5 Order of tabs in an application2.6 Visible rows in a default table window2.7 Display of entire dialog or popup window

3 Style and Details3.1 Capitalization in tabs, labels, and other GUI text 3.2 Abbreviations3.3 Default data in fields 3.4 Section titles3.5 Fields that reference other applications 3.6 Entry fields for SQL expressions3.7 Color to emphasize important labels

4 Accessibility4.1 Alt-text for hyperlinks, images, and icons4.2 Keyboard use for all interactions4.3 Color to enhance, not convey, information4.4 Pictorial representations to enhance, not convey, meaning

5 Reference

ui best practices

Documents

db v ui best practices

entry fields

related fields

default screen layout

default table window

default data

order of tabs

popup window