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/customPreferences.png > ). > > 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 > _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
