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/customPref... ). 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. Thanks, Caty
On Tue, Jun 24, 2014 at 5:33 PM, Ecaterina Moraru (Valica) < [email protected]> 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/customPref... ).
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.
Thanks, Caty
Hi 2014-06-25 8:38 GMT+02:00 Ecaterina Moraru (Valica) <[email protected]>:
On Tue, Jun 24, 2014 at 5:33 PM, Ecaterina Moraru (Valica) < [email protected]> 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/customPref...
).
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?
That would be good, but not in priority.
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.
Adding hints worth the efforts, because Usability is important. The refactoring is more about avoiding technical debt and it would be a shame to not have usability improvements because we do not have the time to do the perfect refactoring, IMO.
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.
For the copy of keys, we already have http://l10n.xwiki.org/xwiki/bin/view/L10N/Refactoring that could help.
Thanks, Caty
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
On Wed, Jun 25, 2014 at 8:38 AM, Ecaterina Moraru (Valica) <[email protected]> wrote:
On Tue, Jun 24, 2014 at 5:33 PM, Ecaterina Moraru (Valica) < [email protected]> 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/customPref... ).
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 https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwik...
Thanks, Caty
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
participants (3)
-
Ecaterina Moraru (Valica) -
Guillaume "Louis-Marie" Delhumeau -
Thomas Mortagne