[HIG] Coleen: HIG review comments

[Coleen Baik <Coleen Baik Sun COM>]

Dear authors:

Great job in putting this together, and thank you, it was a feat!

Overall comment: 

Now that I've reviewed some of this, I think perhaps you might want to
use the "Usability Principles" section as a sort of appendix, or
something that follows the meat of the HIG -- kind of a wrap-up, more
vague, short and sweet summary of the detailed guidelines in the rest of
the document.  Otherwise, it starts the HIG out making it sound
substanceless and fluffy, overvague, and unclear.


INTRODUCTION
============================

Grammar and Wording:
----------------------------
Bullet #1 - Reword first clause, subject (interface elements) doesn't
match with pronoun (they)

Bullet #2 - Insert "to" between "able" and "accomplish."  Change
"making" to "make."

Paragraph #3 - Delete comma between "effectively" and "and."

Paragraph #4 - Replace "aspects" with a more appropriate word, perhaps
"rules," "strategies," "ideas."

General - Stay away from vague, motherhood-and-apple-pie type of
salestalk, where you sometimes make claims that are highly subjective
and not grounded in data.  Pretty much all of the bullet points are in
this vein:

	"Because interface elements... users can learn to use your 
	program faster"

	"Users...will be able to accomplish tasks quickly and easily
	because the interface won't cause confusion or make things
	harder"

	"When users... your application will continue to look right"

	Faster by what meter?  Harder according to whom? 
	What does "look right" mean? What does it mean that an				"interface
won't cause confusion?" 
	What promises are you making for GNOME that may be impossible to
	keep?

	What is a "unique GNOME" flavor?

	You may be able to say what you want by wording things more
	concretely.



Usability Principles: Design for People
=======================================

Grammar and Wording:
----------------------------
Paragraph #1 - Excise references to pronouns such as "we" and take on a
more objective tone (e.g., "We believe that these principles are
important for all application development" to "These principles are
fundamental to application development," although this is still a
statement without support -- it's a bit redundant and may not even need
to be in the document.)

(Side note pertaining to entire HIG: 
The style that seems to be being used in the HIG is very... motherly.
"Remember that the purpose of any software application..."
"The first thing you should do..."
"The important thing is that you know..."

This may not be the most useful way to exhort people to follow
guidelines.  A guideline document is a manual of sorts and should
provide GUIDELINES, not motherly "advice" that comes across as
imperative.  This impression may simply be a byproduct of the wording
style.)

Paragraph #3 - The basic idea here is that knowing your user base is
useful in software application development.  This is pretty much what
you say again and again for the duration of three paragraphs.  Make the
last paragraph more concrete, perhaps list a few major books that are
the industry standards in design.

What is the purpose of the last sentence in Paragraph #3?

Paragraph #3 - Delete "(many of which are extremely useful)."  


Usability Principles: Don't Limit Your User Base
=================================================
                    : Accessibility
                    =============================
                    : Internationlization and Localization
                    ======================================

Grammar and Wording:
----------------------------
Paragraph #2 - Wording in the parenthetical clauses are potentially
unclear.  The first clause, for example, could be read as either: "by
not using color, only to display critical information" or "by not using
color only, to display critical information"  Is there a more succinct,
elegant way to reword the items in this list?

Paragraph #4 - Change L10n to l10n or L10N, and if the latter is chosen,
change i18n to I18N.



Usability Principles: Create a Match Between Your Application...World
=====================================================================

Content:
----------------------------
Paragraph #1 - Patient chart example: great metaphor!

Paragraph #3 - Yes, Macintosh has been hammered for the
trash-can-ejects-floppy model but it is a pretty widely recognized way
to do such a task... some people have been using the MAC for so long
that they might find this suggestion bizarre, because it's become normal
for them to use that metaphor to eject CDs and floppies.  Maybe mention
Macintosh to be upfront about the reference?


Usability Principles: Make Your Application Consistent
======================================================

Grammar and Wording:
----------------------------
Paragraph #1 - The first sentence is unclear, and maybe a dangerous
statement to make in such vague terms.  Perhaps mention that you are
talking about applications in a certain context, and not ALL
applications in general (even badly designed ones).  If you are talking
about applications in general, then what you say in this first sentence
is probably not what you mean.  You value consistency, but in what way? 
Do you mean that developer software should adhere to certain guidelines
that are more important for developer software, or that button text
should be in all bold, or...?

Perhaps you mean that consistency is important WITHIN an application,
because you have control over that?  You do NOT have control over
applications designed by others, although consistency between all
applications ever designed is of course the impossible ideal.

Paragraphs #2 & #3 are very clear and succinct.  If you clarified the
first sentence in this section, I think you're good to go. 


Usability Principles: Let Users Know What's Going On
======================================================

Grammar and Wording:
----------------------------
Paragraph #1 - replace "appropriate"s in the first sentence with
something a little less vague and subjective.  E.g., "Keep the user
informed of what's actually going on through timely and succinct
feedback."  That's still vague, but less so, and OK if you follow up
with definitions of timely and succinct.  

For example, in Sentence #3 of Paragraph #1, back up "timely" with
"immediate" or "within 0.3 seconds" or something of the like (it would
help if the latter were an industry standard) after "provide" and before
"feedback."

Replace "audio" with "auditory" in "Feedback can be visual, audio, or
both" to keep the parallel construction consistent with "visual," which
is an adjective in this context.


Usability Principles: Let Users Know What's Going On
======================================================

Grammar and Wording:
----------------------------
Paragraph #1 - You could probably delete the first two fluff sentences
here (there's no substance in them) and start the third with:  "Don't
clutter your interface or overload the user with buttons..."

Paragraph #2 - What do you mean by "cleanly aligned" or "misuse" of
"color or graphics?"  Maybe say:  "Make sure that dialog elements are
aligned and spaced according to guidelines, and do not use too many
graphics..." or add: "An example of misusing color can be showing font
in bright yellow against a white background, where contrast is
insufficient to provide adequate legibility."


Usability Principles: Let the User Be in Control
======================================================
No comments.


Usability Principles: Forgive the User
======================================================

Grammar and Wording:
----------------------------
Paragraph #1 - Delete the first two sentences, they are gratuitous. 
Start with the third sentence: "Whenever possible, the user..."
and perhaps add in the sentence after "actions:" "in most situations,"
or "via the likes of a Cancel button or an Undo menu item."  Perhaps
expand this paragraph, now only one sentence, with a couple more
sentences that follow it with the additions mentioned above.

Paragraph #2 - Add an example thusly in the second sentence:
"However, this type of confirmation should be avoided except in extreme
cases (such as leaving a system in a transitional state when prematurely
leaving an installation)."  Start the next clause as a new sentence.

Paragraph #3 - Add "a" between "destroy" and "user's."


Usability Principles: Enable Direct Manipulation
======================================================
No comments.


Desktop Integration
======================================================

Grammar and Wording:
----------------------------
Paragraph #1 - The first sentence doesn't make sense.  Is "with" the
correct conjuction to use there?  Maybe that's throwing off the
meaning.  Or there may be missing words between between "elements" and
"to basic integration."  Or "elements" is a wrong word to use. Reword:

"Applications need to fulfill two requirements in order to integrate
smoothly into the GNOME Desktop user environment."

Paragraph #2, or the first requirement - Is there another word we can
use besides "entry?"  People might not know what that means in this
context.  You mean a menu item, rather?  Reword:  "An application should
create/insert an menu item for itself in the panel menu," if indeed the
application does this automatically.


Desktop Integration: Placing Entries in the Panel Menu
=======================================================

Grammar and Wording:
----------------------------
Title - Again, I don't think people will understand that you mean "menu
items" by "entries."  Consider rewording throughout HIG, especially
since the term "menu item" has been used before and "entry" seems to be
referring to the same thing elsewhere in the guidelines.

Paragraph #2 - Example of sub-applications?  E.g., StarOffice Writer,
StarOffice Calc...  perhaps finish the second sentence after "in just
one of these categories" then start a new sentence with: "In the case of
application-suites such as Evolution or OpenOffice, a menu item per each
sub-application should be placed in separate categories.  For instance,
For OpenOffice, sub-application blah should go under blah, while
sub-application blah2 should go under blah2."  

Not quite sure what is meant by "in the appropriate category(s)."


Content:
----------------------------
For Menu categories - Isn't there a GNOME-CORE default of "Settings?" 
Maybe that should go under "System," although I don't know how far you
want to bury something as commonly looked for as the menu item for
configuration dialogs. 


Desktop Integration: Menu Entry Captions
=======================================================

Content:  
----------------------------
What menu entry captions are isn't clear.  It sounds like you mean "menu
items."  Why are there multiple names for the same thing?  Menu items
have been called "entries" "entry captions," "names," and "items."  This
may be confusing.

Great examples following the third paragraph, but there are so many and
a lot of exceptions to the rule that it's confusing...

Paragraph following example 4 - Perhaps you can use a table for the
standard naming case and the exceptions, with rules and examples
succinctly shown.  This would lessen the confusion in this long section
where things are referred to only as "first format" instead of via a
more specific reference (see the tip, or whatever it is that's
highlighted with the i in a circle).  This is necessary because people
usually use these documents not as a straight-read-through doc, but as a
reference that they look up items in.  

Graphics here would be useful as well, showing each possible scenario
(perhaps 3 small graphics with callouts).

Example 7 - This sort of thing is probably better shown in context, as
in a graphic, because it's confusing to read; I at first thought it was
a typo, but then I recalled that earlier it's suggested not to use
"GNOME" in the "captions."  


Desktop Integration: Menu Entry Captions
=======================================================

Content:
----------------------------
Example 9 - 12 - Instead of using the verb in the imperative form, it
seems to be more of a standard to use it in the active form: e.g.,
instead of "insert special characters into documents," use: "inserts
special characters into documents."



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

Content:
----------------------------
(Side note:
Who is your end-user for this document?  Some of your users will surely
be technically-savvy, some might not be.  Some people might not
understand or need to understand coding and MIME database providing the
mapping between documents and applications.  This is tantamount to
exposing the underlying technology when it may be an interface or
graphic designer  with limited knowledge about the nitty gritty stuff
beneath the outer layer of an OS reading this chapter...)

...I've been poring over these pages and commenting with a finer
granularity than I probably should have, but there's a lot of work that
could be done to improve this document -- my comments touched mainly
upon just the wording and grammar, but there's much that can be done for
the content as well.  I did not have an opportunity to comment on
content in detail.

Here's all I've got for now, but if you want more comments, I'd be glad
to keep sending them -- seems like we're running out of time, though.  


Coleen