RE: ANNOUNCE: Style Guide available for review.

[Paul Hepworth <phepworth s-vision com>]

> This is the first revision and should be considered a
> draft.  I am looking for feedback and additions to the
> policy lists.  Thanks!
> 
You asked for it; you got it.

"Documentation for the application should be written using DocBook"
add 
"... and must provide at least a manpage and preferably html
documentation.  (If html documentation is provided, the manpage may
simply be a stub telling how to access the real documentation.)"

"At least a single menubar should be present in an application. If it
seems appropriate to the specific application, the use of a floatable
menubar is encouraged."
Prefix the above sentence with "By default."
It should be possible to hide the menubar in favor of pop-up menus
and/or toolbars only, if appropriate.
Also, some applications are a more logical fit for a modal dialog rather
than a traditional menu-adorned window.  These should contain at least
one of Close/Okay/Cancel buttons, and if a menubar is not provided, a
Help button.

(Can we force window managers to provide a [?] button for use with short
"what is this?" popup descriptions?  If so, all controls shall respond
to the "what is this" message.)

'The menubar must conatin at least two entries: "File" and "Help".'
If it is more appropriate for a particular application, some label other
than "File" may be used.

Add this item:
"All menus must be navagable by mouse using both pull-down (drag) and
drop-down (click) actions and by keyboard using cursor keys and
accelerators.  Each menu item should have a unique accelerator."

"Applications that are document based ( wordprocessors, spreadsheets,
web page editors ) should contain menu entries in the "File" menu for at
least the last four documents that have been accessed."
Reword as "Applications that are document based (wordprocessors,
spreadsheets, etc.) should contain a recent document list in the "File"
menu.  The list shall either hold four items or shall be
user-configurable as to the number of items."

'The "About" button will create a dialog...'
                         ^^^^^^ "display"

"Please make use of the gnome_about widget."
        ^^^^^^^^^^^ "use"

"The "Help" menu should contain the top level contents of the
documentation."
Confusing.

"..., except for user generated lists (bookmarks, etc.)"
Append "which may initially contain no items."

"Modal dialogs should be avoided wherever possible. Please use them only
when changing global application variables."
replace with "Modal dialogs should be avoided wherever possible."

"All dialogs should default to a set minimum size."
replace with 
"All dialogs should be resizable, defaulting to a minimal size, but
saving the size set by the user, even across sessions."  (I HATE dialogs
with tiny listboxes when I have a 21" monitor at very high resolution.
Let me use my ample screen space to make the application easier to use!)

"Applicatins should not allow users to change the default bindings for
common operations."
I *strongly* disagree!  See my posting on the key binding standard.

"All operations that have a deterministic time to completion that lasts
more than three seconds should indicate progress using a progress bar."
Should this be configurable (system-wide, per user) instead of
arbitrarily three seconds?  (I don't like to see progress bars unless
the operation takes more like ten seconds.)



nitpicking:

be careful of use of "should" and "must" -- I saw some "shoulds" that
should be "musts."

Many typos; please run ispell.


"Menu items that have bindings ... 
right justified of the menu item label."
                ^^ use "on" or "in" instead 

All operations that do not have a deterministic
time to completion should indicate progress using
a dialog that contains either an animated icon of
                                               ^^ "or"
some sort of changing number to indicate progress.
^^^^^^^^^^^^ "a"

Please place periods and commas inside the quotation marks, not outside
(We programmers get used to putting them outside, but the typographical
standard is to have them inside the quotation marks; it looks much
better that way especially when you have a proportional font.)
Likewise, parentheses should not be separated from the enclosed text.


IHTH


Paul