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/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.
This already exist. See https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-oldcore/src/main/resources/ApplicationResources.properties#L46 > > >> >> Thanks, >> Caty >> > _______________________________________________ > devs mailing list > [email protected] > http://lists.xwiki.org/mailman/listinfo/devs -- Thomas Mortagne _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
