[xwiki-devs] [Investigation] Administration Hints

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. Thanks, Caty