[HIG] Must-change list

[Adam Elman <aelman users sourceforge net>]

[Note: where I use "I" in the questions below, I mean I as the 
reader, i.e. a GNOME developer.]

Entire Document
---------------
1. The title is now "GNOME 2.0 Human Interface Guidelines," removing 
the "Mini".

2. We need a "Feedback" section which answers the following questions:

* How should I give feedback to users about what is going on in my 
program?  Specifically,
  - How should I let the user know that a lengthy, cancellable 
operation is in progress? (i.e. use progress bars, replacing section 
4.7)
    + When should I use a determinate progress bar, and when an indeterminate?

  - How should I let the user know that a background operation is in 
progress? (use the status bar, perhaps replacing 4.8?)

  - How should I let the user know that an error has occurred, or 
another event which the user needs to know about?
    + What kind of alert box should I use, and how should it appear?
    + How can I write effective error messages?

3. We need a "Windows" section which answers the following questions:

* What kinds of windows can I have in my application, and when are 
they appropriate?
  - Document/"Primary" windows, which should contain a menu bar
  - Utility windows (floating toolbars, properties windows, etc.)
  - Dialog boxes, which are discussed later.

* What is the difference between SDI, "Controlled SDI", and MDI? 
When are they appropriate?
(This may be a policy we need to discuss, and may be too 
controversial for us to fit in here at this point).

4. We need an "Icons" section which contains the advice given in 
section 6 for menu icons.  This is equally applicable to Toolbar 
icons, etc.

5. There are many points where direct allusions to the APIs might be 
appropriate so that we can help developers find the right way to do 
what they want in GTK.  Greg, perhaps you could identify the points 
in the document most in need of this?

SECTION 1. Introduction
-----------------------
1. We will replace Seth's intro with Maciej's alternate introduction, 
with the following changes:

* We're not really covering the philosophy and general design 
principles behind the GNOME UI, so we should remove that sentence.
* I'd like to add the following text at the end (comments welcome):

These guidelines are, like the rest of the GNOME project, created and 
maintained primarily by volunteers.  If you are interested in 
participating in contributing to future revisions of the GNOME Human 
Interface Guidelines or other usability projects related to GNOME, 
please see http://developer.gnome.org/projects/gup/ for further 
information.

If you're not convinced that usability is important to your 
application, we recommend reading Seth Nickell's essay, "Why We Care 
About Usability (And So Should You)". (linked)


SECTION 2. Menus and Toolbars
-----------------------------
Section 2.1: Menu Principles

1. The section on popup/contextual menus (2.1.2) should be removed to 
its own second-level section elsewhere in this section.  It should 
include the suggested guidelines which Calum proposed.  (Maciej, if 
you or somebody else wants to convince the GDP folks to switch to 
"contextual menu", I'm 100% for that, but otherwise we'll stick with 
the GDP).

2. The rest of section 2.1 should be rewritten to answer the 
following questions:
   * What windows should have a menu bar?  What windows should not 
have a menu bar?
   * What should I put into a menu? ("actions and attributes" per mac HIG)
     - How many items can I have in a single menu? (at least 2, fewer than ?)
     - How should I arrange items in the menu? (most frequently to 
least-frequently, but more importantly grouped by relationships)
   * How should I name menu items?
     - Menu items should be named with verbs, nouns, or short verb or 
noun phrases.  Menu items may form verb phrases with the title of the 
menu, for instance "Edit -> Preferences".
     - Use the same capitalization recommendation as Calum makes.
   * How should toggled menu items behave?  Read the comments in the 
commented HIG, as well as p. 44 of the Mac Aqua HIG.
   * When are submenus appropriate and how should they be used? (see 
Maciej's "My review, part 1" as well as the commented HIG).
   * When menus and/or menu items cannot be applied to the current 
document or the current selection, what should I do?  (Make menu 
items insensitive, remove entire menus from view.  Menus should only 
be removed as a result of user actions, never system state.)

3. The section on shortcut keys and access keys (renamed from 
"Shortcuts and Accelerators" to match the GDP guidelines), 2.1.7, 
should be moved to the keyboard navigation section, although a 
reference should be kept to showing the shortcut key and the 
underlined access key in the menu.

Section 2.2 Standard Menus

1. Section 2.2.1, the File menu, should indicate explicit rules for 
what to do with non-document-centric applications besides games.  For 
example, think about:
* an IRC client
* an instant-messaging app
* an email client
* a monitoring tool for a web server

Some of the items should presumably be there, but not all.  Should 
the name "File" be kept for those?  If nothing but "Quit" is 
appropriate, what should we do?  (menus with 1 item are generally 
bad).

2. Policy decision: dump the "Options" menu and recommend "Edit -> 
Preferences" instead.  This is still a little up in the air, so I'll 
also include it as a policy question.

3. We need to also specify the following menus: View, Window.  Other 
folks have suggested other menus (Format, Tools, etc.), we could add 
those as well, but might not want to.

4. For GNOME 2.0, we will stick with the Print/Print Preview/Page 
Setup thing.  Let's talk about that more for the next revision.  We 
may want to add "Send to..." and/or "Publish..." items in the File 
menu, however.

Section 2.3 Toolbars

1. We should only show toolbars that comply to our recommendations, 
and we should recommend a single kind of toolbar control.

2. We should take mpt's comments on the browser layout into 
consideration, and rethink this section in terms of making a 
stronger, specific recommendation on both office-type and 
browser-type toolbars.

SECTION 3. Dialogs
------------------

Section 3.1 General Principles

1. This entire section needs to be rewritten.  We need to distinguish 
utility windows (properties windows and floating toolbars, as well as 
torn-off menus and things like that) from actual dialog boxes (Open 
dialog (modal), Find dialog (modeless), etc.) Here are some things 
that this section should cover:

* What is the difference between a modal and a modeless dialog box?
  - What is the difference between application-modal and 
document-modal? (Can we make that distinction in X?)
* When should I use a modal dialog or a modeless dialog? (Open or 
Save should at least be document-modal if not application-modal, Find 
should be modeless, Format Paragraph should be modeless, etc.)
* How should I lay out buttons on a dialog box, either modal or 
modeless? (We have to be clear and unambiguous on this point.  Maciej 
recommends taking the existing proposal and dropping it in; this is 
my recommendation as well.  Where is the latest version of this 
proposal?)
* When should the actions in the dialog be instantly applied, and 
when should they require a user action (i.e. a closing button) to be 
applied? (If the dialog is modeless and modifies properties of the 
selection, for instance "Format Paragraph", it should be 
instant-apply; otherwise it should wait until the user takes an 
action, for instance "Find"?)

2. We need to remove the distinction between "Action buttons", 
"navigation buttons", "closing buttons", and "help buttons".  This 
distinction is unclear and makes the button layout description very 
difficult to understand.  We should just describe how to lay out the 
buttons in a few common cases.

3. The section on druids (3.1.1.3) should be moved elsewhere in 
Section 3, and should a) be less dismissive of druids, and b) include 
Calum and Maciejs' suggested principles for druids (in the integrated 
comments)

4. Dialog titles should match the menu item that brought up the 
dialog, if it was brought up by a dialog.  We should recommend titles 
for dialogs which were not.

Section 3.2 Standard Dialogs

1. Add a few more standard dialogs: Print, Print Preview, Save 
Changes, and file target (not saving or opening).

SECTION 4. Controls
-------------------

1. See Maciej's and Calum's lists of missing controls.
2. Add screenshots for all of these, at least, correctly used.
3. Move progress bar notes to Feedback section.
4. Move status bar section to Feedback section.  Might want to add a 
note in Menus & Toolbars section about using controls on the status 
bar.

SECTION 5. Layout
-----------------

Add many screenshots.  I think that will help solve most of the ambiguities.

SECTION 6. Integrating Applications with the Desktop
----------------------------------------------------

1. Move the section on icons (6.1.1) to its own chapter.
2. Move the technical detail to a separate document (but provide a 
pointer from the HIG).  The HIG should include a paragraph describing 
the effects we want to see.
From mjs' review:
* This separate document should cover .mime, .keys, .application and
  .desktop files, and should apologize for .desktop and .application
  files being different.

* The separate document should _not_ suggest installing a .mime or
  .keys file for mime types already defined by the system, only for
  custom app-specific ones. In particular, gnome-vfs already defines
  all the intersting info for text/html.

SECTION 7. Mouse Interaction Basics
SECTION 8. Keyboard Navigation Basics
SECTION 9. Simple Reality Checks

See specific comments in reviews and in the integrated comments 
version of the text.

Adam


--