[HIG] REVIEW: Desktop Integration

[Suzanna Smith Eng Sun COM]

Comments on Desktop Integration Chapter 

General Comments
----------------
This chapter seems a bit wordy so the majority of my comments are aimed at 
tightening up the text. 

I also feel that not enough tangible recommendations called out as guidelines. 
I think recommendations need to be called out as guidelines if we want them to 
be followed...readers are much more likely to scan this document than to sit 
down and read the bulk of the text to extract recommendations on their own.

It seems like the organization of information relating to menus is a little
confused. There is somewhat detailed information about menus in this chapter, 
such as menu entry naming conventions and tooltips, that I would expect to see 
in the Menus chapter. If a reader jumps directly to the Menu chapter because 
that is what she is interested in, she will entirely miss recommendations about
menu entry naming conventions or tooltip recommendations. I don't think we 
should assume that the reader will be digesting this document from beginning 
to end so I don't think we should expect the reader to look in a chapter titled
"Desktop Integration" for information on Menus. It doesn't make sense to 
duplicate this information so I would recommend restructuring this chapter
so that the menu-related information in this chapter is moved to the Menus
chapter.

If you move this information, you are left only with the last section called 
"Providing a Connection between Documents and Applications." This section seems 
to be more about programming tips, largely referring to external technical
sources, than making recommendations about the user interface. I question 
whether this section is necessary, and if it is determined that it is, I 
question whether it should exist in its own chapter and if that chapter should
be the first chapter after the Introduction and Usability Principles. Perhaps
it can be rolled into a different chapter?

Those large issues aside, here are specific comments on the existing text in
this chapter.

Placing Entries in the Panel Menu:

I was surprised that this did not mention that applications also need an icon
as part of their entry in the Panel menu. And will we be making any 
recommendations like, "in order to have an entry in the Panel menu or any of
its sub-menus, applications must provide an icon or use a standard icon"?

A screenshot or mock-up would be a helpful and interesting way to illustrate 
the types of entries that can appear under the menu categories listed. Also,
will we make any specific recommendations about which categories applications
should go into? I think we need to provide a little more explanation about
what the distinctions are between the categories listed. It might also be 
helpful to list example things that should *not* be included in various
categories. I don't think we can over-spell or over-explain things enough,
since we will have developers and designers from all levels of experience
and knowledge.

Menu Entry Captions:

I was surprised to see the word "captions" used. Is that GNOME-specific 
terminology? I am used to "menu entry labels". If "captions" is not 
GNOME-specific terminology then I recommend "labels" or whatever the 
documentation style guide might have settled on. Or, if you mention that the
panel refers to captions/labels as "names", why don't we refer to them in the
same way?

The presentation of information in this section is disorganized. I have
taken a stab at reorganizing the information and rewriting the section as
follows to clarify the message:

<begin rewrite>
"Menu entries require labels/names to textually describe the application. Users
are more likely to find your application if it placed in the proper category 
and the name that appears in the menu includes a descriptor of your 
application's functionality along with the application name. 

User testing of MIT's Athena system revealed that users had difficulty finding 
the file manager because they were unfamiliar with the name 'Nautilus'. They 
did not associate the word 'Nautilus' with the concept "file manager". For this
reason it is recommended that the menu entry label/name include a descriptor
of functionality in addition to the sometimes obscure application name. This 
will be especially useful to users of systems where numerous applications are 
installed by default, and to novice users.

Recommendation: The naming convention for menu entries should follow the format
APPLICATION_NAME APPLICATION_CATEGORY, where APPLICATION_CATEGORY is a general
class of application such as "Email Client", "Word Processor", etc.

o Example 1. ...
o Example 2. ...
o Example 3. ...
o Example 4. ...

In some cases an application's name will be clear enough that a descriptor in 
addition to the application name would be extraneous. For example, "Font 
Selector" does not need an descriptor.

Recommendation: If you are adding your application to a menu, follow the
naming conventions of the pre-existing applications in the same application
category. For example, if there is an application called "Foobar Email Client"
and you are writing a new program called Baz, name your application "Baz Email
Client". **

There will be times when it does not make sense for a menu entry to consist
of the application name and an application class descriptor. An application's
name might be sufficient to convey the application's functionality, such as
the Time Tracking Tool. Other times, the addition of an application class
might result in redundant and unuseful information. For example, listing all 
the entries in the Games menu as "APPLICATION_NAME Game" would be awkward and 
redundant since games are the only items in the Games menu.

Recommendation: If no appropriate application class exists, the menu entry for 
an application may follow the format APPLICATION_NAME. This format should only 
be used when an application class is not necessary or would provide redundant 
information to the user.

If possible, remove explicit mention of GNOME, X-Windows or other platform
details from menu entry labels/names. Menu labels/names exist to assist users
in navigating menus and finding tools needed to accomplsh their tasks. The 
menu entry labels/names should not be cluttered with technical details not 
critical to successful completion of the user's task.

o Example 5. ... 
  (NOTE: there is a type(?) in "Example 7: A caption for Same Gnome"; in the 
  example it reads "same _game_". To honest, I'm not even sure what this 
  example illustrates.)
o Example 6. ..."
<end rewrite>

What the above rewrite addresses:
- Information is more organized and the writing is tightened up; extraneous
   information is removed. 
- Examples are tucked in closer to the points the illustrate.
- Specific recommendations are called out. I think this is key...of course, a
   document-wide style for calling out recommendation/guidelines needs to be
   agreed upon.

The last few sentences of the last paragraph are rather confusing. I would 
just remove them (I did in my rewrite ;). I think example #8 is made clear
by the recommendation to remove mentions of "GNOME" and by earlier discussion
of using application classes. I don't think the unclear discussion about 
dropping "client" adds anything to the discussion. If this is an important
point (and not just another example), then it needs to be conveyed more 
clearly.

** Are we making recommendations about the terminology of general application
categories? For example, are we recommending that the name for email 
applications be "Email Client", "Mail Client" or "Email"? We'd better make 
recommendations for the standard applications and application classes if we are
advising people to follow the format of pre-existing menu entries.

Menu Entry Tooltips:

I suggest the following edits to tighten up this section:

"Tooltips are used to learn about a new environment and to quickly explore the 
available functionality of applications in that environment. 

Recommendation: Tooltips should be provided for all menu entries to give the 
user information about the tasks they can perform with each of the applications 
in a menu. Tooltips should not be overly verbose, but should be more descriptive 
than the label/name used in the menu.

Recommendation: Panel menu tooltips should be phrased in verb form to describe 
the actions users can take with each application. 

o Example 9. ...
o Example 10. ...
o Example 11. ...
o Example 12. ..."

I removed the last two sentences of the paragraph as I found them confusing
and not entirely necessary. 

Are we recommending any style or punctuation do's or dont's for tooltips? I
noticed all the examples given have no punctuation. We should involve a Doc
writer to review any recommendations or examples where we provide strings of
text because people will follow examples exactly as we provide them...

Providing a Connection between Documents & Applications:

I'm not a fan of this section title. I'd prefer "Mapping Document Types
and Applications" or something similar.

As mentioned much earlier in this feedback, I don't feel like this section 
is right for user interface guidelines; it seems more like programming 
guidelines or programming "how to". I recommend moving the menu-related 
information to the Menu chapter, which would leave just this last section
as the second chapter in the HIG. Somehow that doesn't seem right. If this
section must stay I recommend finding a more appropriate home for it.

Probably everyone has mentioned this, but the first and third paragraphs 
are repeats of one another.

The beginning of the second paragraph is terribly unclear. I'd suggest 
rewriting the first sentence as: "For each data type there is a perferred
list of first class application handlers..."

The second sentence is a very vague and open-ended recommendation, which
isn't very great if we're trying to come up with guidelines people will
follow. Of course most engineers are going to list their apps as "first
class" or on the "preferred list". I think we need to make a recommendation
here if we are going to devote space to this topic. What is our 
recommendation of what apps should make it onto a preferred list and
which should not? What would the criteria for apps to be perferred? If
there are criteria, then we should spell it out and make a more firm
recommendation.