Re: ANNOUNCE: Style Guide available for review.

[Christopher Blizzard <blizzard appliedtheory com>]

Paul Hepworth wrote:
> 
> > 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.)"
> 

DocBook will generate HTML among others.  I'd like to stay
away from man pages if at all possible.  Maintaining one
form of documentation is easier for developers, and more
importantly, less confusing for users.

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

True, I though of this when I wrote this and wondered when
someone was going to say "but what if...".  I've reworded it
to be a little more clean and only apply to applications
where it's appropriate.

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

This is dealt with in the Keyboard Binding Policies.  Also,
I don't think that every menu item needs an accelerator.  It
can get really confusing for users.

> 
> 'The "About" button will create a dialog...'
>                          ^^^^^^ "display"
> 
> "Please make use of the gnome_about widget."
>         ^^^^^^^^^^^ "use"
> 

Better grammar.  Yep.

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

You're right.  It was put there to generate a response.  I'm
wondering what people think about what the minumum items in
the documentation should be.  I don't know.  Maybe that's
too specific to each application.  I'm ripping it out for
now.:)

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

Ok.  When a key binding standard is both available and the
software is ready for use, we can add information about the
key binding standard.  However, I personally feel that
individual applications still have no business changing the
key binding for a common operation that may be used in other
places.  Changing that in a global area is fine, but not in
each program.

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

Yeah, I know.  At the top of the document I intend to make
formal definitions and then go through the document and make
sure that all of the shoulds and musts and must not's are
all in the right place.

> 
> Many typos; please run ispell.
> 

Yep.  Done.

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

That's not what I mean.  The binding should be listed on the
menu right of the label ( text ).

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

Yep.

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

Yep, coding habits coming through. :)  I'm actually aware
that punctuation is supposed to be inside of quotes but it's
hard not to think of "File" as a string, even when it's at
the end of a sentence.  I'll try to clean it up.

> IHTH
> 
> Paul
> 

Thanks for the comments, Paul.

--Chris

-- 

------------
Christopher Blizzard
AppliedTheory Communications, Inc. 
http://odin.appliedtheory.com/
blizzard@appliedtheory.com
------------