Re: schema files

[Christian Rose <menthos gnome org>]

mån 2003-07-14 klockan 14.35 skrev Ole Laursen:
> > What I tried with point i) above is to stress the need for actually
> > useful <long> descriptions; descriptions that explain in more detail
> > than the <short> description what they key actually does control and
> > what alternate settings for this key there are etc. Such descriptions
> > add much valuable information for the users that need to modify the
> > values of such keys.
> 
> I agree with that - but many things are more or less self-evident. For
> instance, the key "applet_height". Having "Applet height" is OK for a
> short text, but adding "Height of the applet in pixels." for the long
> text is non-sensical. One might as well reformulate the short text to
> "Applet height in pixels".

I think having the <short> description as short as possible is a useful
goal -- this makes the relevant keys easier to find in long listings of
keys. Further details about units used, different possible values etc.
should go into the <long> one. This helps keeping the <short>
descriptions as just short, human-readable "names" for the keys.


> > More work for us, but fulfilling the user's needs are more important.
> 
> Sure. I think the advice needs to be elaborated. What about:
> 
>   i) Make sure you have <short> and _useful_ <long> descriptions for
>      all keys. If a <long> description does not contain any new
>      information (e.g. if it is just a reformulation of the <short>
>      description), it is usually better to leave it out; it will just
>      create more work for the translators.

As mentioned above, I don't think I agree with this. Even if a <long>
description is just a slightly more verbose reformulation of the <short>
one, I do think it helps.


> PS: There's really no need to send the message to me privately too.
> Please just post to the list.

Ah, I usually just use reply-to-all instead of reply-to-list. Most
people don't mind.


Christian