[HIG] General editorial comments

[Adam Elman <aelman users sourceforge net>]

1) Every section and subsection in this document should answer a 
specific question or set of questions which a GNOME developer might 
ask.  I do not propose that we rewrite this as an FAQ; the questions 
are useful mainly for focusing the author's attention.  However, 
authors should be very clear about what questions are being asked and 
answered in each section, and should consider logical follow-on 
questions, and answer those as well.  This will be important in 
rewriting some of the sections which are currently organized in 
unclear ways.

Remember that the audience is GNOME developers.  The questions we 
must answer are the questions that GNOME developers should be asking: 
"What should the menubar in my application window look like?" "Should 
I use an option menu or a list box?" "Should I use MDI or SDI?" "What 
buttons should appear on this dialog box, and in what order should 
they appear?"  Note that even several of these questions are not 
clearly answered in the current doc!

2) We must eliminate wishy-washiness.  This is a document of 
guidelines; guidelines must be clear, unambiguous, and difficult to 
misinterpret.  If developers dislike or disagree with the guidelines, 
they are welcome to question them and suggest alternatives.  It's 
better to promote doing something a single way, even if it is 
sub-optimal, than to allow every developer to come up with his or her 
own way of doing it.

Remember that the primary goal of the HIG is to promote a more usable 
GNOME environment by promoting a consistent user experience.  By 
saying "there are multiple 'right ways' to do this", we leave it up 
to the developer and thus destroy consistency.  This means that 
rather than saying "Well, there's no 'right way' to do this", we MUST 
say "Here's the way to do it," even if we don't have a strong logical 
justification for that way.  For instance, if every GNOME app uses 
"Edit->Preferences" to modify application settings, the user will 
know where to go to modify application settings, even though we all 
know that Edit->Preferences is not necessarily the best way to 
specify this in all situations.

Never say "Y will usually appear like X."  This is a guideline, not a 
descriptive document.

Never say "Where possible, you should..."  In every case I've found 
that in this document, it is _always_ possible to follow the 
recommendation.  If there are common cases where it really is 
impossible to follow the guideline, we must be explicit and 
unambiguous about what causes those cases, and what should be done as 
an alternative (see #3).

3) We must eliminate ambiguity.  We need to be clear and specific in 
every section about a) what question is being answered in that 
section, and b) what the answer is and, specifically, what the 
developer must do to be in compliance with the guidelines.  If there 
are exceptions to a guideline, we must be clear about what case 
triggers that exception, and what the proper response should be in 
that situation.  Never, ever, say "Sometimes it may be appropriate" 
without listing at least _some_ cases that trigger that "sometimes."

For instance, we need to be clear on what developers of the following 
types of applications should do for menus:

* Non-document-editing applications (like an IRC client or an IM app or a game)
* SDI or "controlled SDI" document-editing applications (like a word 
processor or a graphics editor)
* MDI document-editing applications (if we allow this at all).

4) At the same time as #3, we must not get too caught up in corner 
cases.  There are some small number of apps, for instance, for which 
it might be appropriate not to have a menu bar.  If that's very rare, 
we don't need to provide clear specifications for that case in the 
HIG.  We need to address common concerns, not _every_ concern.

The balance between #3 and #4 is, unfortunately, something that will 
have to be determined on a case-by-case basis.  #3 is probably more 
important; #4 is something that is more important as we try to edit 
for length.

--