Difference between revisions of "Settings Wording"

Revision as of 21:55, 7 February 2006

This page describes the wording style that gnucash tries to follow in the description of the GConf configuration keys.

HIG

Gnome Human Interface Guidelines (HIG): http://developer.gnome.org/projects/gup/hig/2.0/gconf-keys.html

General wording

Pretty much the only helpful suggestion from the HIG is that the "short description should be less than 8 words". To achieve this, any "fill words" like "This key..." or "Enable this..." or even "this" should not be used in the short description.

Other wordings that should not be used, neither in the short not in the long descriptions:

• This key ...
• Whether or not...

OTOH, in the long description I suggest the description may begin with a common wording depending on the key type. However, so far I wasn't able to find a really good common wording, so for the time being I'll only copy the existing wordings here. We should decide which ones should be kept and which ones should be replaced.

Existing wordings

bool key types

bool keys; existing wording in gnucash:

• This key indicates whether...
• Set this value to TRUE to...
• If this field is TRUE then...
• If set to TRUE then...
• If TRUE, ...
• Whether or not to ...
• This key indicates whether to...
• This setting controls whether or not...
• Setting this value to TRUE tells gnucash to...
• A value of TRUE says to...
• Set this key to TRUE to ...
• Enable ...

Sigh. One obvious thought is that users don't see any value labeled TRUE; they only see a checkbox that may be activated or deactivated.

int

• This value specifies...
• This dialog is presented ... (obviously the flag for "don't show again")
• This setting controls...
• This key contains the...

string

• This key contains...
• This setting determines...
• This setting allows...
• This setting controls how...
• This field specifies...

list string

• This key contains a list of names which ...
• This key indicates which ...
• This key indicates how ...

list int

• This key contains the coordinates describing...
• The X,Y coordinates...
• This value contains the X,Y coordinates...

float

• This field sets the number of...

Tools

To view all schemas files in one big chunk, run the following command in the gnucash top directory:

cat `grep schemas po/POTFILES.in`