On Wed, Jun 25, 2014 at 8:38 AM, Ecaterina Moraru (Valica)
<valicac(a)gmail.com> wrote:
On Tue, Jun 24, 2014 at 5:33 PM, Ecaterina Moraru
(Valica) <
valicac(a)gmail.com> wrote:
Hi devs,
One problem users are facing in the Administration is that the fields are
advanced and not well documented. One of the simplest ways to improve this
is to provide hints for all the entries (an example for the Profile
Preferences
http://design.xwiki.org/xwiki/bin/download/Improvements/UserRoles/customPre…
).
I've investigated the status of our default sections found in
Administration at
http://design.xwiki.org/xwiki/bin/view/Proposal/AdministrationHints
You can also see the Status column that displays the 'coverage' of hints.
I've also provided images of how it currently looks in the Section column.
Now, providing hints for Administration fields is not that easy since we
need to reach some agreements:
Q1: Labels and Hints come in pairs. When adding new keys do we:
- stick with the current naming for the Label and just add a '*.hint' key
for the Hint or
- should we deprecate the Label key and use for both the new translations
naming convention?
Q2: We should decide on a convention for Hint. We are currently using:
hint, tip, explanation, description. I prefer 'hint' since it's in our
Vertical Form standard, but Bootstrap for example is using 'help-block'.
Q3: Where do we put them? The majority of the keys are found in
ApplicationResources.properties. Should we extract them and create
Translations pages for them in the appropriate module?
Q4: Should we implement
http://jira.xwiki.org/browse/XWIKI-7783 for the
cases where we extract the values from classes?
Q5: What about the content of the Hint message? Ideal it would be nice for
the owner of the module to help provide the Hint text since some fields are
advanced and even I don't know what they are doing. We could have a person
responsible for reviewing the final text in order to have the same 'tone'.
Q6: It's very nice to stop from time to time and refactor things, but do
we consider the effort of doing this to be of worth? This question applies
for:
- refactoring on one side and
- adding hints on the other.
Q7: We need a mechanism to 'Deprecate and Copy' the keys (somehow like
renaming the keys from the no-standard-naming to standard-naming). We need
it because when introducing new keys we lose all the current translations.
Of course a solution would be to manually copy the translations values, but
like in the Administration case, if we were to 'fix' all the keys we will
have a lot of values, for a lot of languages.
This already exist. See
Thanks,
Caty
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs