Re: RSG

[Kai Wetzel <k wetzel welfen-netz com>]

Tom Vogt wrote:

[...]

> Rebel Gnome StyleGuide
> ======================

Nice name :)

My suggestion for the outline, but you'd want to concatenate I guess:

Acknowledgements
Foreword
Introduction
  (what we talk about, "Declaration of Intent", <sigh> :)
Heritage
  (Shortly mentioning historical aspects, Mac, Amiga,
   NeXT, point to the appendicular References section).
Concepts
  (I'd _love_ to have a summary of the most fundamental
   concepts you want to be applied to construct a useful GUI -
   the Mac guide is very much centered on this stuff IIRC.
   Shortly mention the goals of good GUIs, the trade-offs, etc.
   Then, come back to the principles when you apply them in further
   chapters.)
Means
  (Apply the concepts, "GUI elements" you say.  Many subsections,
   I'll add some comments below.)
Cookbook
  (What's in GNOME concretely to make this stuff happen ?
   App skelleton, "standard" dialog boxes, cool widgets which
   add some groove to the dev. env., mention GUI builder,
   stock pixmaps and common GNOME icons repository, translation
   service, this mailing list for asking back, gettext <sigh>, etc.)
Standards
   (keybindings "Accelerator keys", cut 'n paste,
    etc., could be removed if you want to put all this
    stuff in the appendix respectively in "Means".
Appendices
   References
   ...

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

Well, IMHO this should read something along the
lines of "better graphical user intefaces".

After that, you could mention why you value cooperation between
"Linux" desktop project (such as GNOME, KDE, as well as
some minor projects) so low.

I _personally_ would say that both aspects should
be addressed (Nice _overall_ Linux desktop _and_
improvements which can only be made if a group which
cooperates so closely as GNOME does, "the GNOME feeling",
whatever)

Even if your focus remains as is, it should be mentioned here
_why_, I think.

> 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.
> The additional goal of this Style Guide is to make the interface as easy
> and intuitively as possible, without taking away power and customizability.

It's a trade-off in many cases, something for the
"Concepts" section I mention above.

> 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.

Well, I strongly appose the notation of compliancy
levels, in fact, oppose any notation of "compliance"
in this regard.  I beleive the guide should give hints
about how GUIs can be made better using GNOME, why it's
important to work together and have a consistent interface,
etc.  However, the programmer shouldn't be talked into
compliancy by peer pressure or "GNOME compliant - level 1,2,3,4"-
buttons but because they realize it's agood idea :O)
What makes you beleive you _need_ the means of compliency
and levels ?  We're talking about usually pretty smart
engineers and geeks, after all...

> Chapter Two     Default Gnome Elements
> ======================================

I'd place this below in the Cookbook section, but this
order probably makes sense, too...

[...]
> Chapter Three   Gnome Application Style Guide
> =============================================
[...]
> 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.

First, "Prog" really doesn't sound nice.  If
at all, make it "Program" :O)  I can't explain
why I don't like the short form, maybe it's conceived
ugliness ?  I dunno =O)

Anyway, I'd suggest to re-consider the whole
file-menu-sucks debate.  There are some argumnents which
can IMHO show that the File menu isn't as bad as
it's opponents have been trying to show, and most
of all, we don't have a very good alternative, either (IMHO)

I'm not saying all this criticism has no point - it
surely does - but what's the setting we want to
work on in the future ?  "Program" doesn't sound like
a very "document"-centric approach per se - but it could
be used to construct this approach, maybe.

Pie menus, NeXT-like menus - all things which should
be elaborated on.  We should list what's good/bad, the
trade-offs, the logic and nonsense in the given
approaches, etc.  Mandating a certain split, possibly just
to set GNOME apart with the argument that the existing
solution doesn't make sense isn't good IMHO.

I had the impression that many people din't try
to understand the _advantages_ of the File menu
approach before saying "no" to it (but this may
only be the case because we have so much "debate"
here, so little "brain-storming" :O(

> C1 - The "Prog" menu is a special Gnome menu that contains items
> relevant to the application as a whole.

Well, up to now I'd say putting it in help makes
a lot of sense.  But it depends on the setting...

> The topmost entry in the "Prog" menu must always be "About". The
> last entry in the "Prog" menu must be called "Exit". This item
> will exit the application completely.

In order to make the "Ctrl-Q" accelerator keep it's
inherent logic, I'd suggest to stick to "Quit" (in the english
language, that is ;)

> The "Prog" menu must be the leftmost entry on the menubar
> and must be fully left justified.

"first" entry on the menubar...

> 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.

Hmm, I don't think I get the point of going into such detail
here as it doesn't seem to be a problem with any large
number of apps...

> 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...".

Consider to recommend "About appname..." instead !
E.g. in an OpenDoc/OLE-like app this could actually be two
entries, e.g. "About CoolShell..." and "About <active part>" ...

> C1 -  Menu items that contain sub-menus should indicate this with
> a right justified arrow.

Hmm, yes.  But IMHO "C1" and "should" appear overused here ;O)

> C1 -  Menubar items and menu entries that are currently not
> available in the application should appear grayed out.

Again, the heavy use of should/must/etc. doesn't make
reading easier, to say the least.  The point is clear
in this case - but "Grey out menu entries which are not available"
would be nicer IMO.

> C2 - The "Help" menu must contain at least one entry called
> "Gnome", that starts the Gnome helpbrowser with its main page.

Hmm, I'm not sure I like this.

> C1 - All menus should contain at least one entry, except for user
> generated lists ( bookmarks, etc. ) which may initially contain
> no items.

Good point.

> 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.

"Please use ..." hmm.  IMHO it's cool to have some
diversity here.  How about telling what items commonly
appear in such box and then say that GNOME makes it easier
by providing a widget and it's shown in the cookbook section below
how it can be used ?

> 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 "..."

Hmm, I think just New is clear enough _if_ the app can
only handle one kind of document (avoid redundance).
the "..." is good, but Netscape's New > [submenu] approach
is another good way if only a few kinds of objects are
supported.
 
> C3 -  If it seems appropriate to the specific application, the
> use of floatable menubars is encouraged.

What's the value ?

> 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.

Yikes, please make this an option.  Tens of tiny 16x16
icons nobody can distinguish even at 32x32, '98 ugliness if
you ask me ;O)

> C4 - [Pie Menus]

Good idea.  Should be fledged out more.  If you really
want a "GNOME mandates make it good:"-guide, put it in the
"more ideas" section =O)

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

Hmm, you don't like a messge box which just reads
"Dismiss" or "Continue" ?  Should be given another thouigh,
also add reasoning when done.

> C2 - Modal dialogs should be avoided wherever possible.

Good point.  How ?  Exmaples ?  What cases fall in the
"not possible" category ?

> C2 - The default highlighted button for a dialog should be the
> safest for the user.

I disagree.  The default button should be the
most likely confiramtion unless it is irreversible.

> C4 - The default selection should be user-customizable.

What do you mean by this ?

> C2 - All dialogs should default to a size large enough to display
> all of the information in the dialog without making a resize
> necessary.

Hmm, like Netscape resizes the save as dialog ?
Plain ugly.  Better make it remember the last resize
by the user !

> C2 - All dialogs should set the titlebar with an appropriate
> string.

That's important !

> 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.

We need to explain when to use the "OK" button.
The discussion of OK vs. verbs ended abbrupty IIRC.

> 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.

You're correct about apply.  OK should only be greyed
if the current state of the dialog gives insufficient info.
(Which should be avoided in most cases, e.g. the
"Change name" dialog will contain the old name in the
entry box w/ all letters selected.)

> C1 - If a dialog contains more than one button for the
> destruction of that dialog,

"termination" ?

> ( for example, an "OK" and a "Cancel"),
> the affirmative button should always fall to the left of the
> negative.

Sad, but you seem to like this crap :(  I'd strongly
suggest to put the confirmative action in the
bottom right corner for Latin-script languages:

Do you want yellow ?
[Help]            [Cancel] [Make it so]

Of course if Make it so is not reversible, make
"CANCEL" the default button in this case.
 
> C2 - "Dialogs" that only display information with no user interaction
> should have only a single button labeled "close".

"Dismiss" =O)
 
> C3 - If you have a situation where a dialog might spawn another
> dialog please consider using a notebook instead.

It depends.  Notebooks don't represent
hierachical relationships very well IMHO.  There
should be guides when they are approriate, when not.
 
> 3.3  KEYBINDINGS
> ----------------
> C1 - All menu items, menubars, dialogs and notebooks should be
> navigable from the keyboard.

not sure about "from", anybody ?
 
> C1 - Menu items that have bindings should list them right
> justified of the menu item label.

How about using common terminology and call these
"keyboad accelerators" ?  Otherwise good idea I think.

> C2 - All applications that have common operations should use the
> binding interface that is outlined in the gnome key binding
> standard. Using the interface outlined in this standard will
> allow users to define  their own set of favorite key bindings and
> still maintain consistency across applications.

(accel keys...) Please mention that it's planned to
offer a keybinding config framework for GNOME apps.
 
[...]
> 3.4  PROGRESS BAR
> -----------------

It's about indicating showing progress of lengthy tasks,
the header "PROGRESS BAR" isn't very good I think.
(can't think of a catchy alternative right away...)

> C2 - All operations that have a deterministic time to completion
> in which no other obvious application activity would normally be
> taking place should indicate progress using a progress bar. This
> progress bar should begin its activity at the beginning of the
> operation.

Hmm, not very clera IMO. What kind of task do you
envision here ?  "Preparing game map" ?  Ok, but
"downloading ftp://..." ?  IMHO the (external) task
inspector was a cool idea mentioned by some contributor
before ...  Listing printer spool info, Netscape dowloads, etc.

> C1 - Where possible, all operations that use a progress bar
> should have a cancel button as well.

Lengthy tasks should be interuptable, good point !

> C2 - Operations where a cancel button would be harmful to the
> application or user data should use a confirmation dialog.

Good.

> C3 - Progress bars can be either set into the application panel
> or create their own dialog, depending on the individual design of
> the application.

(and the externel stuff...give some criterions here, when use
which (indicators ...))

> C2 - All operations that do not have a deterministic time to
> completion should indicate progress using a dialog that contains
> either an animated icon or changing number to indicate progress.

"Deterministic time" is a hard concept.  Should be worked out
I think.

> 3.5  NAVIGATION
> ---------------
> C1 - All functions of the application should be available through
> the default user interface.

You mean the default should not hide away functionality ?
If yes, I agree completely.
 
> C1 - If the "Exit" menu entry or button is used or a destroy
> event is emitted, and the user has unsaved information, the
> application should pop up a modal dialog to ask the user if they
> are sure they want to exit the application without saving.

Or, whether they want to save changes before quitting, since
that makes the confirmative response the save one which
is often a good idea (not always, unfortunately ...)

> C3 - Document based applications should contain four menu entries
> in the "File" menu for the last four documents opened. In the
> event that there haven't been four documents accessed, entries
> that have not been filled should be grayed out.

I agree w/ the previous poster that the section shouln'd
be there in the beginning.  (Possibly show both separators, though,
I'm not sure.

[...]
> 3.8  THEMES
> -----------
> C3 - [Color-reactiveness]
> 
> C? - [Appearance Guidelines (Graphics, etc.)]

Good point.  Especially general considerations, with
examples (maybe even good/bad, even though bad examples
tend to be remembered more easily (thus end up beeing applied ;)

[...]
> 3.12  DISTRIBUTION
> ------------------
> C3 - Licensing under the GNU public license is strongly
> encouraged.

Hmm, this could be something for the introduction
or preamle, but prprietary apps shouldn't be excluded
in any way (I understand you don't want to do this, just
wanted to mention it ;)
 
> Chapter Four    Writing Gnome Programs
> ======================================

"Cookbook":O)
 
[...]

Nice stuff overall !  I hope I'll make it to the
conference tonight, though I have an appointment
w/ my dentist tomorrow morning =°O

As a last comment, internationalization should be mentioned
more often...

Best regards,
kai