COMMENT @----------------------------------------------------------------------

	Copyright (c) GeoWorks 1992 -- All Rights Reserved

PROJECT:	PC GEOS
MODULE:		User Interface
FILE:		StyleGuide

DESCRIPTION:

	$Id: StyleGuide.doc,v 1.3.34.1 97/03/29 03:37:38 canavese Exp $

------------------------------------------------------------------------------@

****************************************************************************
	  Thoughts on Style Guide for PC/GEOS  (Doug)
****************************************************************************

We need a Style Guide.

I didn't always think this was going to be the case -- one of the tenants of
the "Generic UI" concept is that the software manipulates the interface for
the application to conform to the style guide of the current specific UI.  So,
we don't need a style guide, right?

Wrong.  There are number of problems that a Style Guide could help to correct:
        
        1) The Generic UI concept itself works only to the degree that
           the developer sets up their "Generic Interface" correctly.

        2) We've taken some shortcuts on path to the one true Generic UI.
           Basically, there's more of Motif & PM in the generic UI than
           might be possible (For the most part, this doesn't restrict new
           specific UI's from doing their own thing, it just means that PM &
           Motif can be simpler, because they don't have to work so hard
           to enforce their own style guide rules).  So... there are things
           like "Textual monikers should in general be in lower case, with
           the first character capitalized", and the standard ordering of
           of main menus, that developers have to adhere to.

        3) Applications, despite all the zillions of style-guide compliant
           objects we provide, still have some of their very own code.  (Oh,
           no!  how'd that happen? :)  
 
Taking a look at Microsoft's new "Application Design Guide", I get the feeling
that a Style Guide for PC/GEOS could be put together fairly quickly --  
they devote exactly 4 pages to they "Principles of User Interface Design"
chapter, which consists of a few paragraphs and a Bibliography.  Of the
remaining 212 pages, I'd estimate that a good two-thirds of it consists of
details that are hidden to developers in PC/GEOS (spacing between buttons in
reply bar, proper appearance for a print dialog, etc.)

I'll start collecting pertinent info as I run into it, & place it in
/Library/User/Doc/StyleGuide.doc.  


****************************************************************************
	  Moniker Guidelines  (Matt)
****************************************************************************

Use the following guidelines when creating text monikers. "Text moniker" 
as it is used here refers to any text in menus, buttons, dialog boxes, and
other areas of the screen that label elements of the user interface.

1.   Captalize every word except

	o. Coordinating conjunctions (such as "and," "but," "or")
	o. Articles (such as "the," "a," "an")
	o. Prepositions of three or fewer letters (such as "on," "in,"
	   "of").

        Examples:

	    Baud Rate
            Characters per Second
            Rate of Insertion Point Blinking
	    Speaker Volume

2.   Capitalize prepostions of four or more letters.

        Examples:

	    Remove Files With Folders
	    Number From First Page

3.   Capitalize the first and last words, regardless of their parts of speech.

        Examples:

	    About OS/90 Write
	    Position Text At

4.   Capitalize the second word in hyphenated compound modifiers, except when
     the second word has two or fewer letters.

     Examples:

	 Use Large-Capacity Disk Device
	 Copy From Built-in Disk Drive

     NOTE: A compound modifier is a modifier, such as an adjective, that
     consists of more than one word. For example, the adjectival modifier
     "large-capacity" in the phrase "large-capacity disk drive" is considered
     a compound modfier because it consists of more than one word (it modifies
     the noun "disk drive").  The modifier "large" in the noun phrase "large
     disk drive" is a singular modifer because it consists of one only word.

****************************************************************************
	  Message Guidelines (Matt)
****************************************************************************

Any messages that the user sees should be clear, concise, immediately
understandable, and consistent with all other messages in the system.

1.   Write directly and matter-of-factly. Address the user as a peer.


2.   Write mostly in the active voice. Most sentences convey action and the
     active voice is the best way to do so.

	Use:  Please insert the system disk into drive A.

	Not:  The system disk should be inserted into drive A. (passive voice)

     TECHNICAL NOTE: You can think of the active voice as a way to write 
     sentences so that they use active, empowering verb to do their work
     rather than some weak form of the verb "to be."
     
     Technically, whether the grammatical subject of the sentence is the
     performer of the action or whether it is the recipient of an action
     determines if the sentence is active or passive. In an active voice
     sentence, the grammatical subject of the sentence performs an action
     (e.g., in the sentece "Ted threw the ball," Ted, the grammatical subject
     of the sentence, is the performer of the action, namely, throwing the
     ball). In contrast, in a passive voice sentence, the grammatical subject
     of the sentence doesn't perform an action but is instead the recipient of
     one (e.g., in the sentence "The ball was thrown by Ted," the ball, the
     grammatical subject of the sentence, is the recipient of an action,
     namely, being thrown). In both example sentences, the actual performer of
     the action is the same (Ted in both cases throws the ball), but only in
     the active voice sentence is Ted the grammatical subject of the
     sentence.

     Sometimes a sentence has an implied subject, as in the examples "Please
     insert the system disk" and "The system disk should be inserted." Both of
     these sentence have an implied "you" as the subject:

		[Will you] please insert the system disk.

		The system disk should be inserted [by you].

     The same rules still apply.

     RULE OF THUMB: If the main verb in a sentence contains some form of the
     verb "to be," and the sentence is not an identity statement (that is,
     of the form "x is y"), then the sentence is probably in the passive
     voice.


3.   When you want the user to make a choice, ask a question.

      Use:   Do you wish to save the file "My Document" before quitting?

      Not:   The file will be saved before quitting.

  a.  Do not add redundant imperatives to a question.

      Not:    Do you wish to save the file "My Document" before quitting?
              Click "Yes" to save the file. Click "No" to quit without
	      saving.

  b.  Never use imperatives in place of a question.

      Not:    Click "Yes" to save the file "My Document" before quitting.
              Click "No" to quit without saving the file.

  c.  Ask questions using the second person indicative ("you").

	Examples:
	      Do you wish to delete the file "My Document"?

	      Do you wish to allocate more memory to print this document?

	      The disk "Your Stuff" has documents on it. Do you wish to erase
	      them?

	Not: 
	      Should I delete the file "My Document"?

	      The disk will be formatted.

  d.  Whenever possible, use questions that have yes/no responses. When "Yes"
      and "No" result in a progressive action--that is, when they both do
      something--you should also provide a "Cancel" option. However, when
      "No" does not result in a progressive action--that is, when it is
      synonymous with "Cancel"--the "Cancel" option is not necessary.

  e.  Assume the user can figure out how to respond to a question without
      benefit of an explanation. In other words, leave elaborations to
      the manual.
      
      Ask straightforward and concise questions, provide simple sets of
      responses, and give the users a safe way out in case they don't know
      how to respond (e.g., a nondestructive "No" or a "Cancel").


4.   Use the second person imperative mood when you want the user to perform
     an action. The imperative mood takes the form of a command or a
     direction.

     Examples:

	Please insert the disk "Steve's Stuff" into Drive A.

	You may now turn off your computer.


5.   Avoid the verb "to be" in all its forms. As the most common verb in the
     English language, it is also the weakest. Use active, empowering verbs
     instead.

	Use:  An error occurred while reading the disk.

	Not:  There was an error while reading the disk.


6.   Be neither chummy nor pretentious. Avoid sophomoric interjections like
     "Voila!" and technical jargon with which the user may not be familiar.


7.   Use short sentences and short words. They aid quick comprehension.


8.   Place the subject of the sentence near the verb and put them both near
     the beginning of the sentence. Avoid long subjects.


9.   Avoid anticipatory phrases that delay the start of a sentence. In
     particular, avoid the following:

     	It is...
	There are...
	It is necessary...
	It is important...


10.  Use sentence-style capitalization.

	Use:  An error occurred while reading the disk.

	Not:  An Error Occurred While Reading the Disk.


11.  Use a period at the end of a statements that form complete sentences.

12.  Do not use periods at the end of sentence fragments.

13.  Do not mix sentence fragments and full sentences in the same message.
     The exception to this rule is when a sentence fragment acts as a title.

14.  Place only once space after standard punctuation marks

15.  Avoid using technical adjectives and nouns as verbs ("interface," for
     example).

16.  Avoid the following abbreviations:

	Abbreviation	Use instead
	============	===============
	etc.		and so on, and so forth
	e.g.		for example
	i.e.		that is

****************************************************************************
	  Dialog Guidelines (Andrew)
****************************************************************************

Rule #1:
        Whenever possible, use one of the StandardDialogBoxType and
        UserStandardDialog. These are standardized boxes/messages for many
        common file operation errors.

Rule #2:
        Whenever you can't use one of the StandardDialogBoxType, use
        UserStandardDialog anyway, but pass your own error message strings.
        Do *not* create a custom dialog box in your .ui resource --
        use the standard one.

Rule #3:
        When you are creating your own error message string, be simple, but
        also verbose. Give the user as much information as possible.
        If the disk is full, don't put up a box saying "Error Creating File".
        Put up a message like "There is not enough room on the disk to create
        'Foo Document'. Use GeoManager to delete files" instead. Always
        attempt to give the user an idea of what he can do to resolve the
        problem (Another example: "The spelling dictionary file is missing.
        Try re-installing PC/GEOS").

        If you want a look at some great (IMHO) error message strings, look
at the SDS_* strings in "/staff/pcgeos/Library/CommonUI/CSpec/cspecFile.ui".
It can be a pain to give good error messages to the user, but it is one of
the most important aspects of a truly user-friendly environment.

