[HIG] Coleen: HIG review comments II

[Coleen Baik <Coleen Baik Sun COM>]

Here's a second set of comments, continuing from where I left off in the
last message.  

I would also like to offer to do the figures for you; I was the
illustrator for the Java Look and Feel Design Guidelines: Advanced
Topics, which just came out, and have experience with designing mockups
and illustrations for guidelines.

Let me know, and I'll insert figures where I feel they're needed; that's
pretty much what I did for the JLF DG AT.

Coleen


Desktop Integration: Providing a Connection...Applications
==========================================================

Content:
----------------------------

Paragraph #1 - Add figure, "'File Types & Applications' capplet in the
Control Center"

Again, there's really tech-y language here, and wondering if that's what
you meant to put in here: "first class handlers," "MIME database..."  

Also, I see you put a placeholder for the last paragraph in the
section.  In general, you might want to make this section less prone to
having the eyes-glazed-over effect on readers by toning the language to
be more open to all users, both techy and non-techy.  It'd be fine if
you said this document is just for developers, but you didn't, so:

Instead of saying: 

"The Application & MIME database provides a mapping between document
types (as defined by their MIME type) and applications."

Try something like:

"MIME is the acronym for Multipurpose Internet Mail Extension, and it's
the protocol that tells applications what a file type is (e.g., GIF,
Word, HTML, text) in order to open it... [segue to using "Application &
MIME database" and the mechanism in the context of GNOME]"


Windows
==========================================================

Grammar & Wording:
----------------------------
Delete "many" in "Windows are an essential part of many graphical user
interfaces.

Replace "apparent" with a more appropriate word in "This section applies
to top-level windows as they are the only windows apparent to the
user."  Define "top-level" windows, maybe that will help make the
sentence clearer.


Windows: Parts of WIndows and System Interaction: Titles
==========================================================

Grammar & Wording:
----------------------------
Paragraph #1 - Change "windows" to "window" in first sentence.  Use
present tense, change "will have" to "has." 


Content:
----------------------------
Paragraph #1 - "Windows which ordinarily do not stand alone, such as
menus, must have titles when they do stand alone."  Menus are windows? 
This definitely needs a figure, especially if you're not going to reword
this.  I've never seen any menu that's standalone, unless you're
counting context menus, and in my view, they are NOT standalone as far
as the definition goes in referring to windows; they are obviously
dependent upon another object, namely the content of a window...  I
guess if they're "context" menus outside of an application, just on the
desktop, they can be considered standalone... I recall seeing titles on
those menus, but not sure -- my current installation of GNOME doesn't
give me menus outside of applications or off the taskbar.

Title formats probably should be given in a more succinct for first, in
something like a table, then details should be given describing each
format, the latter which you've done.


Windows: Parts of WIndows and System Interaction: Frames
==========================================================

Grammar & Wording:
----------------------------
Paragraph #1 - "An applicaton window should not attempt to provide its
own frame, but should provide hints to the window manager for the
desired frame type."

This sentence is misleading.  Try something like:

"Frame look and feel | Frame types should be decided by the window
manager, not by individual applications.  All applications on a desktop
should have one frame type, since only one window manager can be running
at any given time on one desktop."


Content:
----------------------------
Paragraph #1 - What are "shaped windows?"  Be careful about using
non-industry-standard terms or esoteric terms.  People will be
confused.  There are usually terms that people are familiar with.  Take
a look at other guidelines such as:

http://java.sun.com/products/jlf/ed1/dg/index.htm

And go to the Windows section to look at semantics.


Paragraph #2 - Define "Frame commands" explicitly.  Explain what YOU
mean by "window type," even if it seems common sense; it's such a vague
term that people will have different definitions, some more specific
than others.  When able, provide lists, either complete or
example-based.  Don't assume that everyone will know what you are
referring to at any given time.  This sentenct "Frame commands for each
window type are shown by name when they may be provided" is therefore
unclear.


Windows: Parts of WIndows and System Interaction: Modality
==========================================================
This section needs SERIOUS work, in both content and grammar.

Grammar & Wording:
----------------------------
Paragraph #2 - "An object mode" not "A object mode."

Content:
----------------------------
Paragraph #1 - The definition of mode/modality needs work.  How is the
reader supposed to know what you mean by "limitation of actions a user
may take?"  You may want to also give concrete examples such as:

"Windows are modal or modeless.  For example, if you are trying to save
a document in a word processing application from the filechooser under a
name that is already taken, you will likely get an alert box (a kind of
window) which warns you that you will be overwriting that file if you
choose to continue.  Until you choose what to do by clicking on a button
in that window, you will be unable to do anything else on your desktop. 
That window is modal because interaction with the desktop is limited to
that window.  If you are composing an email in Netscape Messenger, the
message composition window you are typing in is a modeless window,
because you can choose to stop composing in mid-message and go to
another Netscape window, a terminal window, or the taskbar.  This window
is modeless since interaction with the desktop is NOT limited to that
window."

Such examples are useful to back up guidelines and statements like:
"As such, modes should be avoided."  There is no convincing argument
here for avoiding modes, so far in the section.

Paragraph #2 - What do you mean by "object mode?"  Don't change terms
arbitrarily.  Do you just mean "mode?"  

I won't continue commenting in this section because it's clear that a
significant amount work is still needed here before someone can even
attempt to edit it.


Windows: Parts of WIndows and System Interaction: Focus
==========================================================

Content:
----------------------------
(Side Note:
Just curious... what are the references for all these terms?  (e.g.,
PointerRoot mode)  Perhaps define all these, as easy-to-figure-out they
seem.)

What do you mean exactly by saying that applications can "hint to the
window manager?"  A technique in writing is to define such a thing once,
refer to it immediately by a short, euphemistic term via two enclosing
commas with the "or" conjunction, or using parentheses, and thereafter
always use the euphemistic term.  


Windows: Parts of Windows...: General Communication...Window Manager
====================================================================

Content:
----------------------------
Link to the wm-spec of the Free Desktop Group and the ICCCM.

Link to the Feedback section.


Windows: Primary Windows
==========================================================

Content:
----------------------------
Paragraph #1 - _The Java Look and Feel Design Guideliens: Advanced
Topics_ (JLFDG AT) defines primary windows thus:  "A primary window is
the main window in which a user interacts with a document or data.  An
application can have one or more primary windows, each of which a user
can manipulate independently.  A primary window represents an object
(such as an email message) or a set of objects such as all the messages
in a mail window)."  This is simple, clear and concrete.

Your definition isn't quite there yet; a window isn't just a "view,"
unless you mean something different by the term, and saying "contents of
an image" doesn't sound correct.  Perhaps use the above citation as an
example and go from there.

Paragraph #2 - What is an example of a primary application window that's
NOT framed?  I can think of situations where you can actively take a
frame OFF a window, for example with terminal windows in Enlightenment,
but it looks more like a bug than anything.  Should this be allowed,
even, for windows?

Preface the format examples and frame commands with another paragraph
that segues gracefully into their introduction.
 

Windows: Primary Windows: Single Document Interface
==========================================================

Content:
----------------------------
Here's one way to deal with this.  In JLFDG AT, they didn't really
discuss SDI, which is both preferred and the norm (in Unix, anyway), and
just had a little note for MDI, which they warned against using, and one
of the reasons given was:  "Many users have trouble manipulating the
windows of MDI applications."  Not very detailed but you choose your
battles; this wasn't given much attention.

Windows: Primary Windows: Controlled Single Document Interface
==============================================================

Content:
----------------------------
Figure needed.  Define Control Window.  Explain why you'd want this or
not want this; just saying it's "reserved for expert or special-purpose
applications" is not enough.  And what are the definitions of "expert"
or "special-purpose" applications?

Windows: Primary Windows: Multiple Document Interface
==========================================================

Content:
----------------------------
This section may need expansion.  JLF DG AT defines an MDI application
as:
"An application in which primary windows are represented as internal
windows inside a backing window."  


Windows: Utility Windows
==========================================================
Figure needed.  


Windows: Utilty Windows: Property Windows
==========================================================
Figure needed.  Property Windows aren't utility windows, I don't think. 

Content:
----------------------------
I now see what you're doing with the Title Format and Frame commands. 
Perhaps just introduce these in the first section of the Windows
chapter, then in the rest of the sections leave them as they are, a
constant under each sub-rubric of Windows.


Windows: Utilty Windows: Preference Windows
==========================================================
Figure needed.  This may fit under another sub-category, like Property
Windows, which isn't a utility window in the first place.


Windows: Utilty Windows: Toolboxes
==========================================================
These sections (Toolboxes, palettes...) might not deserve so much
attention.  Utility winodws are toolboxes and palettes, basically.  A
paragraph is probably enough to describe utility windows and mention
what they do, in what contexts they can be found, and list examples. 
There's not a lot to say about toolboxes and palettes in general.



Windows: Utilty Windows: Palettes
==========================================================
See above comment.


Windows: Utilty Windows: Other
==========================================================
Delete this section.


Windows: Alerts
==========================================================

Grammar and Wording:
----------------------------
Paragraph #1 - Delete "object" in "object modal."  

Instead of saying "An alert will have a dialog-like frame," why not have
Alerts under a larger category like "Secondary Windows," where Dialogs
is also another category, at the same level as Alerts?  And don't all
windows have frames?  How's a "dialog-like" frame differ from... a
"generic" frame?  If you're differentiating between such two, you're
contradicting an earlier statement that windows on a desktop should rely
on the window manager for a uniform frame look and feel.

Delete "unwelcome" from third sentence, "intrusion" is enough to convey
"interruption," and the idea of "unasked for notice" without sounding
subjective.

In sentence #4 hopefully you are not using the term "exception" as it is
used in coding (e.g., in Java).  If you are, perhaps you should qualify
it to make that explicit for those that don't code.  

Delete "unanticipated" in the last sentence.


Windows: Alerts: Information Alerts
==========================================================

Grammar and Wording:
----------------------------
Second bullet - What do you mean by "selectable message?"

Third bullet - Be more clear on what you mean by "convenience button,"
or else don't use a slap-on term at all, just say something like: "May
present a button that..." and follow with something more concrete than
just "allow ready access to a relevant object."

Content:
----------------------------
Escape key is synonymous with the "Cancel" button, Enter key is
synonymous with the "OK" button.  They shouldn't overlap, but if this is
a standard convention in GNOME, I guess we can't do anything about that.

Just curious: Where are your stock icons coming from?