Difference between revisions of "Settings Wording"

Revision as of 08:49, 30 July 2016

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): https://developer.gnome.org/hig-book/unstable/gconf-keys.html.en

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 wordings here. We should then decide which ones should be kept and which ones should be replaced.

Some numbers: We have currently 123 different gconf keys in gnucash. Since each key eventually has two description strings, the question of consistent wording is definitely non-trivial. The vast majority (more than 50%) are bool keys. The exact numbers are:

• 55 bool
• 26 int
• 17 list
• 15 string
• 10 float

Recommendations per key type

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.

Recommendations

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:: It turns out bool keys are used in two different ways.

• One usage refers to a key that activates/deactives something user-visible in gnucash. In that case, I propose the following example wording because we don't have to explicitly mention the semantics of active vs. not active:
  • This setting enables the commodity column in the register.
• The other usage refers to a key where the semantics of activated/deactivated are not obvious but correspond to one out of two choices. I propose the following wording so that there is a clear "if active, foo will happen; otherwise, bar will happen" distinction between the two available choices:
  • If active, only the 'active' items in the current class will be searched. Otherwise all items in the current class will be searched.

Existing wording

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.

Two Examples

TODO: Decide on one of the following example possibilities for long descriptions (from here):

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 (from here):

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

Existing wording

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

string

Recommendation: Actually most of the existing wordings are just fine, except that the word "key" shouldn't be used and instead of using either "field" or "setting" we should agree on one. I'd recommend to write always "This setting {contains,determines,specifies}..." --Cstim 05:14, 8 February 2006 (EST)

Existing wording

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

list string

Existing wording

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

list int

Existing wording

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

float

Existing wording

• This field sets the number of...

Tools

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

head -1000 `grep schemas po/POTFILES.in` > allschemas.xml

(which, actually, isn't a valid XML file anymore, but it still looks similar to one.)

To write all 14 schemas files back in the whole trunk from the above created single file allschemas.xml, use:

perl -ne 'if (/^==> (.*) <==$/) { 
  $fname="$1"; open(STDOUT, ">$fname") or die "cannot open $fname: $!"; 
  } else { print; } ;' allschemas.xml

but note that due to the headers of head this will inadvertantly add one newline at the end of all 14 files except the last one. This could potentially be avoided by the following script instead:

perl -ne 'if (/^$/) { $emptylines++; } else {
 if (/^==> (.*) <==$/) {
   $fname="$1";
   open(STDOUT, ">$fname") or die "cannot open $fname: $!";
   $emptylines = 0;
 } else {
   while ($emptylines > 0) { print "\n"; $emptylines--; };
   print;
 }
}; ' allschemas.xml