Re: RSG

[Bowie Poag <bjp primenet com>]

> this is mainly a collection of things discussed here and/or posted earlier.
> I've only written some explanatory text and tried a few clarifications here
> and there. but still - please comment on everything you feel should be
> commented on.

Ok.
> 
> Foreword
> ========
> 
> this is NOT an official document, nor is it in any way related to the
> "official" Gnome styleguide that is being developed by Bowie Poag.

Ok, Tom. Her'es your first official revision:

The (yes) Official GNOME UISG V2.0 is being developed by......

Bowie J. Poag, Dan Kaminsky, Bill Swingle, The entire GNOME GUI mailing
list, and any curious onlookers in the general public who wish to
contribute opinions and ideas via the bi-weekly development conferences
held on IRC. Dan, Bill and I are -maintaining- the project, which is far
different than "developing" it.

> 
> 
> 
> Chapter One	Declaration of Intent
> =====================================
> 
> the purpose of this document is to set forth guidelines for a consistant
> Gnome Look & Feel.

You cant dictate "look and feel". You can only describe the elements which
make for consistant design and implementation. Its not the purpose of a
Style Guide to preclude the user's personal tastes.

> Such consistancy is necessary to help the user find his way around the
> system and all compliant programs easily and without the need to relearn
> basic operations.

Ok.

> The additional goal of this Style Guide is to make the interface as easy
> and intuitively as possible, without taking away power and customizability.

This is impossible. Sacrifices are made across the board to arrive at an
equilibrium between the needs of the user, the needs of the programmer,
and the needs of GNOME.

> one term being used throughout this document is "compliant" or "compliance".
> Being compliant means a program honors the guidelines contained herein and
> thus "fits in" with the other Gnome applications.
> We will define various levels of compliance, and will rate programs according
> to these. This will help users to find consistant programs more easily and
> should help programmers and designers to deal with the issue.

Issue*s*.:)

So far so good. Looks like we're all on the same wavelength when it comes
to the need for Compliancy Levels.

> the levels of compliance are:
> 
> C1 - Mandatory (bare minimum)
>      Contains only the essential styles, so current programs can be brought
>      up to at least some level of compliance fast.
>      C1 features are considered to be of primary importance and non-compliance
>      will be considered a bug for Gnome applications.

Non-compliance isnt a "bug". There will be (and will NEED to be)
applications which are INTENTIONALLY non-compliant. Example: Kai's Power
Tools. Doesn't follow a stich worth of the style conventions of Mac OS.
Its still a good interface, strongly bound to its functionality. You cant
enforce style--only suggest it, and offer incentives for improvement.

Compliancy levels shouldalso  be in ascending order, not descending. C5
should be bare minimum, not C1, if you insist on abbreviating them that
way.

> 
> C2 - Recommended (needed for a proper Gnome app)
>      Features and behavior needed to make an app a full-blooded
>      Gnome app.
>      Only C2+ compliant apps should be considered "true" Gnome programs.

Define "true Gnome programs". I wouldnt exclude programmers in this way,
if I'm reading you correctly. Programmers would begin following eachother,
and not the guide.

> 
> C3 - Suggested (should be there)
>      More advanced, harder-to-implement features, beyond the
>      call of duty, yet still within the core group of styles.
>      Should, but don't have to be implemented in finished programs, in no 
>      way mandatory for development versions.

While we're on the subject, there ARE things which SHOULD be manditory,
across the board, in order to be even rated for compliancy.

> 
> C4 - Optional (fringe feature)
>      "Nice to have" features that are considered useful, but may not
>      be appropriate for all programs and are not necessary even where
>      appropriate.

How the heck are you gonna judge this concretely? This is way too big of a
gray-area. Try defining things more precisely here.

> 
> C5 - Under Development (cutting edge, not official style yet)
>      Experimental features that are not fully implemented or
>      supported yet.  (Will fall into C4 or C3 when fully realized)
> 

These types of applications dont belong in the public domain to begin
with, and therefore should not be judged for compliancy.

> Chapter Two	Default Gnome Elements
> ======================================
> 
> this chapter contains suggestions to the developers of the core Gnome
> applications like the panel, properties and other configuration dialogs,
> help browser and many more.
> We consider these applications important enough to deserve a special
> treatment due to two reasons. First, they will create the first impression
> a new Gnome user has. Second, all other apps will be measured by the core
> applications.
> 
> 
> 2.1  THE PANEL
> --------------
> 
> 
> 2.2  CONFIG DIALOGS
> -------------------
> 
> 
> 2.3  HELP BROWSER
> -----------------
> 
> 
> 2.6  FIND UTILITY
> -----------------
> 
> (has probably to be redone COMPLETELY. look into the interface hall of shame
> and compare.)

Agreed.

> 
> 
> 
> 2.5  OTHERS
> -----------
> 
> 
> 
> Chapter Three	Gnome Application Style Guide
> =============================================
> 
> this chapter contains the various items of interest for Gnome applications.
> They are sorted by topics and marked with C-Levels for compliance.
> 
> (dev-note: the current stuff is a mess, unsorted and all. subchapters should
> be introduced once the main points are clear)

Agreed. 

> 
> 
> 3.1  MENUS
> ----------
> C1 -  If an application uses a menubar, it must contain at least
> two entries: "Prog" and "Help". A third entry, "File" must be available
> if appropriate. In the event that the name "File" is not
> appropriate, another label may be used in its place. In the
> remainder of this document, this menubar entry will always be
> referred to as the "File" entry.

Again, "Prog" is an indeterminant word. There is absolutely no reason to
truncate this from "Program". If you do so, you break visual consistancy.
Thats a no-no. If youre going to do that, theres almost no point in even
writing a style guide to begin with. If you dont set a good example, do
you think anyone is going to come along that will?


(more about "Prog" deleted..)
> 
> C1 -  If a menubar is not present in an application, two buttons
> must be present somewhere labeled "Help" and "Exit". If the help
> for that application does not contain "About" information ( see
> below ) then an additional "About" button must also be provided.

And where do these buttons go? Stuff to think about as the clarification
process continues.

> 
> C1 - Menu items that open dialogs or require additional user
> information should indicate it with a "..."  after the label. For
> example, the "About" menu entry in the "Help" menu should
> actually look like "About...".
> 
> C1 -  Menu items that contain sub-menus should indicate this with
> a right justified arrow.
> 
> C1 -  Menubar items and menu entries that are currently not
> available in the application should appear grayed out.
> 
> C2 - The "Help" menu must contain at least one entry called
> "Gnome", that starts the Gnome helpbrowser with its main page.

Hmmm.. Ill think about this one more before commenting.

> 
> C1 - All menus should contain at least one entry, except for user
> generated lists ( bookmarks, etc. ) which may initially contain
> no items.
> 
> C2 - The "About" button will display a dialog with information
> containing at least the name and email address of the author,
> copyright information, version, and a link to the application
> repository information. Please use the gnome_about widget.

Ok..

> 
> C3 - If the "File" menu contains a "New" menu entry, it should
> indicate what you will be creating. For example, if the
> application creates a new word processing document, it should say
> "New Document" instead of just "New". If the application is able
> to create more than one type of resource, it should indicate that
> it will create a dialog with a "..."
> 
> C3 -  If it seems appropriate to the specific application, the
> use of floatable menubars is encouraged.
> 
> C2 - All menu items that have a corresponding button elsewhere in
> the application that uses an icon should also contain the same
> icon. The icon should be scaled to the proper menu size and be
> left justified in front of the label on the menu.
> 
> C4 - [Pie Menus]

Untested theories do not belong in style guides. They belong in public
forums for debate, and THEN subsequent inclusion. Notice I dont intend on
mandating color-reactiveness into UISG V2.0 .. Despite the fact that I
think its an excellent idea. :)

> 3.2  DIALOGS
> ------------
> C1 - All dialogs should have at least one button that is labeled
> "Close", "Cancel", "OK", or "Apply."

This is vague. Do they need all four? Does the "OR" mean all three, with
the option of a fourth? ..Get my drift? You have to keep these kinds of
things in mind when writing a Style Guide--Because someone IS going to
come to it, looking for clarification.

> 
> C2 - Modal dialogs should be avoided wherever possible.
> 

Agreed.

> C2 - The default highlighted button for a dialog should be the
> safest for the user.
> 
> C4 - The default selection should be user-customizable.
> 
> C2 - All dialogs should default to a size large enough to display
> all of the information in the dialog without making a resize
> necessary.
> 
> C2 - All dialogs should set the titlebar with an appropriate
> string.

Justified in which direction?

> 
> C2 - A dialog which consists of a single entry box shall have its
> OK button be the default (which is to say that enter shall accept
> the entry), and the escape key shall be bound to the Cancel
> button.

Some mention needs to be made around here, of the physical location of
such buttons. There's a whole chapter in UISG V2.0 dedicated to window
construction issues like this.

> 
> C1 - In a dialog the "OK" or "Apply" button should not be
> highlighted until the user has made a change to the configurable
> data in the dialog.

A default should be highlighted, executable by hitting Enter. 


> C1 - If a dialog contains more than one button for the
> destruction of that dialog, ( for example, an "OK" and a "Cancel"), 
> the affirmative button should always fall to the left of the
> negative.
> 
> C2 - "Dialogs" that only display information with no user interaction
> should have only a single button labeled "close".
> 
> C3 - If you have a situation where a dialog might spawn another
> dialog please consider using a notebook instead.
> 

Thats about all I can help you with for now. I've got more work to do,
still.. However, i'm glad you took the time to visit the conference
webpage, and glean some ideas from it. Things are starting to shape up,
but there is still much more work to do.

Bowie