Re: ANNOUNCE: Style Guide available for review.

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

Christopher Blizzard wrote:
[...]
> 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.

Yes.  I could even imagine a help browser which skips
the HTML step intirely.  In fact that's the way I'd like
things to be eventually :)

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

I thing it would be a good idea to identify some
common types of GUI programs, such as "applications",
"desktop accessories", "control panels", etc.
There was a start on this on the fOX mailing list,
Maybe I'll get back to this in a later posting.

Another thing to keep in mind is that we're not
trying to pass a "gnome user interface act" but
writing a guide for programmers to write better,
interoperable GUI software which is a pleasure to
use.  So I think that there are many things which
could be mentioned, even though they are not included
in every program.  E.g. IF an app provides a
"help - table of contents" then the programmer should
know that it's called "Contents" not "Topics" or the
otherways around :^)  Still e.g. a simple app could
live happily with just "Help->About..."

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

How about "show" or "present" ?  (Just some ideas, I don't mind ;)

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

I prefer the phrasing which was presented here which
was written in the spirit of "if you don't want
to waste your time, we've done a nice gnome_about_widget
you could use".  I don't think anything speaks against cool
about boxes if programmers want them, e.g. like the
ones from After Dark screen saver plug-ins.

If you keap the above, it would be good to say why :O)

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

Well, what's commonly used in help menus ?
- Contents           <optional>
- Balloon Help >     <optional>
- About ...
What else ?
 
[...]
> > replace with "Modal dialogs should be avoided wherever possible."

It's ok, but could anyone think of a more meaningful
phrase then "wherever possible" ?
IMHO "wherever possible" should be avoid wherever possible,
especially in UI guidelines ;°)

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

IMHO not in each program indeed, but for each program.

> > 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.
[...]
I personally prefer "shall" and "will" rather then "must"
but I guess it's just me ;O)  Anyway, I'd suggest to
be careful with must, and use "must provide one of the
following" instead if it makes sense.
The gnome isn't giving out compliancy stickers, after all ;O)

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

It should be listed right of the label, right aligned :O)
[...]

kai