Settings Wording

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.

So we need to find out a good wording and style for ourselves. A useful approach is to distinguish the different keys by their key type. For now, we only copy the existing wordins here. We should decide which ones should be kept and which ones should be replaced.

We have something around 150-200 different gconf keys in gnucash. The question of consistent wording is therefore definitely non-trivial. The vast majority (more than 50%) are bool keys.

Existing wordings

bool key types

The bool keys are the vast majority in gnucash. This makes them a good example to find out a way for consistent wording of the descriptions.

Existing wording in gnucash for bool keys:

• Set this value to TRUE to...
• If this field is TRUE then...
• If set to TRUE then...
• If TRUE, ...
• Setting this value to TRUE tells gnucash to...
• A value of TRUE says to...
• Set this key to TRUE to ...
• This key indicates whether...
• This key indicates whether to...
• Whether or not to ...
• This setting controls whether or not...
• 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. Also, the wording "whether or not" doesn't really add useful information here, because the user will always see a checkbox which unambiguously explains that this setting is about something that is active or not. Also, the user doesn't know that these settings are called "keys" internally.

Proposed recommendations for short descriptions: The short descriptions should not be complete sentences; instead, I'd propose to imagine a full sentence beginning with "If this setting is active, gnucash will do xyz". We should use only the latter part "do xyz" as the short description. --Cstim 04:45, 8 February 2006 (EST)

Proposed recommendations for long descriptions:: TODO.

TODO: Decide on one of the following example possibilities for long descriptions:

1. If active, the commodity column in the register will be shown.
2. This setting controls whether gnucash shows the commodity column in the register.
3. This setting enables the commodity column in the register.

Comment: This example refers to a key that activates/deactives something user-visible in gnucash. In that case, I'd vote to use the wording #3 because we don't have to explicitly mention the semantics of active vs. not active. --Cstim 04:45, 8 February 2006 (EST)

TODO: Decide on one of the following example possibilities for long descriptions:

1. If active, only the 'active' items in the current class will be searched. Otherwise all items in the current class will be searched.
2. This setting controls whether gnucash searches only in the 'active' items in the current class. If not active, only the 'active' items in the current class will be searched.

Comment: This example refers to a key where the semantics of activated/deactivated are not obvious but correspond to one out of two choices. I'd vote for #1 so that there is a clear "if active, foo will happen; otherwise, bar will happen" distinction between the two available choices. --Cstim 04:45, 8 February 2006 (EST)

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:

head -1000 `grep schemas po/POTFILES.in`