Design Guideline

Author: Kevin K.M. Chiu
Copyright 2000, Cobalt Networks.  All rights reserved.
$Id: designGuideline.txt,v 1.13 2001/10/11 01:11:37 kevin Exp $

Overview
========

This document describes design guidelines for Cobalt's user interfaces. As
much as possible, these guidelines should be followed when designing user
interface for Cobalt products.

Choosing Widgets
================

There are many widget classes in UIFC. It is, however, not that hard to choose
which widgets to use if we understand the decision path to the right widget.

We shall start with a classification of widgets. There are essentially 4
groups of widgets. They are buttons, containers, form fields and labels.
Buttons can be grouped into typed-buttons and untyped-buttons, Within form
fields, we can group widgets into selectors and typed-fields.

Buttons include Button, MultiButton, AddButton, CancelButton, ModifyButton and
the like.
Typed-buttons include AddButton, CancelButton, ModifyButton and the like.
Untyped-buttons include Button, MultiButton and the like.

Containers include PagedBlock, ScrollList, SimpleBlock, CompositeFormField and
the like.

Form fields include Boolean, DomainName, IpAddress, MultiChoice, SetSelector,
TextBlock and the like.
Selectors include Boolean, MultiChoice, SetSelector and the like.
Typed-fieldss include DomainName, IpAddress and the like.

Labels include Label, ImageLabel and the like.

Picking between buttons, containers, form fields or labels is straight forward.
Buttons are for actions. Containers are for containing other widgets. Form
fields are for inputs and displays. Labels are for labeling things. What takes
more thinking is to select the right widget within these classes because some
of them (e.g. form field) has a lot of widgets.

To pick a container, ask yourself what kind of information you want to contain.
SimpleBlock is good at presenting a small number of information for display
purposes. PagedBlock is good at presenting multiple form fields for a single
entity. ScrollList is good at presenting multiple entities of the same type.
For example, PagedBlock is good at presenting different properties of a user
while ScrollList is good at presenting a list of users. Do not choose a
container simply because of how it looks. UIFC classes represents design
concepts instead of implementation method. This means looks of containers can
change.

A large number of UIFC widgets are form fields. Selectors and typed-fields are
two groups of form fields. If you are looking for a widget for users to pick
value(s) from a limited set of options, use selectors. If you need a widget for
displaying or entering value(s) of a certain type, use typed-fields.

To picking the right selector, ask yourself how many options do users need to
pick from. Boolean is good for binary options such as true/false, on/off,
enable/disable, etc. If there are more options and only one of them can be
chosen, use MultiChoice. It is also good if there are form fields associated
with those options. SetSelector is primary for selecting a small set out of a
very large set of similar options.

Picking a typed-field is very straight forward. If you need to display or have
users to enter an IP address, use IpAddress field. If you need something for
domain names, use DomainName field. Sometimes, the type you are looking for may
not be available. In this case, you can use TextField and TextList widgets.
They are for generic text.

Widget Usage
============

- As much as possible, widgets should have default values.
- As much as possible, widgets should not force users to switch back and forth
  between input devices.
- Must-be-filled widgets should be placed before optional widgets.
- Group related items together and separate loosely related or unrelated items.
- Consistency should be held between pages. For example, if page 1 shows widget
  A and then widget B, page 2 should not show widget A after widget B. Always
  design pages with consideration of the whole site.
- The less widgets there are in an user interface, the better it is. A lot of
  widgets can be minimized through better product design.
- Select widgets that limits inputs to possible options only. For example, if
  there are two flags A and B. Flag B can be true if flag A is true. These
  flags should not be presented by two checkboxes which allows B to be true
  when A is false. Three radio buttons should be used instead. The first one
  being both A and B are true, second one being A is true and B is false, third
  one being both A and B are false.
- Do not use state change buttons (e.g. "on" button that changes to "off" after
  click) because, first, user expect the same thing to happen when they do
  the same thing and second, state change buttons are poor status reporter
  (e.g. button says "off" when the state is "on" and vice versa).
- Make sections inaccessible or obviously not needed at the time they are not
  useful. For example, when a section accessible from a button has nothing to
  offer unless something else is done first, the button should be grayed out.
  Feature parameters are meaningless unless the feature is on. In this case, a
  MultiChoice can be constructed with an Option to enable the feature.
  Parameters can then be attached to the Option, so they are visually
  dependent on it.
- Do not have different pages on PagedBlock simply for navigation purposes.
  Use the navigation system instead because it is easier to navigate. Pages on
  PagedBlock are good for hiding advanced and optional information from the
  user because it makes those information less directly accessible to users.
- ScrollList is used for multiple instances of one type of information. If
  there can only be one instance, always use PagedBlock.
- For items with labels associated with them that needs units defined (e.g.
  disk space), always put units at the end of the label surrounded by
  parenthesis (e.g. Disk Space (MB): 10).
- Form fields that are optional should be marked optional, so that users do
  not feel confused when they do not have anything to enter or waste time
  entering information even if they do not have to.

Text
====

- Always capitalize the first character of all words on buttons
- Always capitalize the first character of all words on labels
- Always capitalize the first character of all words on titles
- Always capitalize the first character of all words on option labels
- Labels must be fully understandable by themselves. Use nouns instead of
  broken phrases
- Round percentage at the decimal point, so instead of 97.05%, use 97%

Wording
=======

Preferred words        | Not preferred words
-----------------------+-------------------------------------------------------
<active voice>         | <passive voice>
<full text>            | <acronym>
<full text (acronym)>  | <acronym (full text)>
<non-abbreviated>      | <abbreviated>
<positive meaning>     | <negative meaning>
access                 | policy, priviledge
add                    | create
correct                | right (means many things)
enable                 | on (means many things)
GB                     | Gigabytes, Gbytes, gb
KB                     | Kilobytes, Kbytes, kb
MB                     | Megabytes, Mbytes, mb
modify                 | change, edit
program                | application
reply                  | answer
server                 | host, machine
setting                | configuration, option
subnet mask            | network mask
