Difference between revisions of "Settings Wording"
(→General wording) |
(→bool key types) |
||
| Line 34: | Line 34: | ||
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. --[[User:Cstim|Cstim]] 04:45, 8 February 2006 (EST) | 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. --[[User:Cstim|Cstim]] 04:45, 8 February 2006 (EST) | ||
| − | Proposed '''recommendations for long descriptions:''': | + | Proposed '''recommendations for long descriptions:''': It turns out bool keys are used in different ways. Maybe we can progress by choosing example descriptions for each of the different ways? Here are two examples: |
| − | TODO: Decide on one of the following example possibilities for long descriptions: | + | TODO: Decide on one of the following example possibilities for long descriptions (from [http://svn.gnucash.org/repo/gnucash/trunk/src/gnome/schemas/apps_gnucash_dialog_prices.schemas.in here]): |
# If active, the commodity column in the register will be shown. | # If active, the commodity column in the register will be shown. | ||
# This setting controls whether gnucash shows the commodity column in the register. | # This setting controls whether gnucash shows the commodity column in the register. | ||
| Line 42: | Line 42: | ||
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. --[[User:Cstim|Cstim]] 04:45, 8 February 2006 (EST) | 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. --[[User:Cstim|Cstim]] 04:45, 8 February 2006 (EST) | ||
| − | TODO: Decide on one of the following example possibilities for long descriptions: | + | TODO: Decide on one of the following example possibilities for long descriptions (from [http://svn.gnucash.org/repo/gnucash/trunk/src/business/business-gnome/schemas/apps_gnucash_dialog_business_common.schemas.in here]): |
# If active, only the 'active' items in the current class will be searched. Otherwise all items in the current class will be searched. | # If active, only the 'active' items in the current class will be searched. Otherwise all items in the current class will be searched. | ||
# 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. | # 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. | ||
Revision as of 09:55, 8 February 2006
This page describes the wording style that gnucash tries to follow in the description of the GConf configuration keys.
Contents
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 wordings here. We should then 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:: It turns out bool keys are used in different ways. Maybe we can progress by choosing example descriptions for each of the different ways? Here are two examples:
TODO: Decide on one of the following example possibilities for long descriptions (from here):
- If active, the commodity column in the register will be shown.
- This setting controls whether gnucash shows the commodity column in the register.
- 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):
- If active, only the 'active' items in the current class will be searched. Otherwise all items in the current class will be searched.
- 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`
