Using a script: IFS=$'\n'; for file in `find . -name LocalDescriptions.properties|grep -v "target"`; do for line in `cat $file|awk -F '=' '{print $2}'|uniq -d|grep -v "^$"`; do echo -e "\nDuplicated items in File: $file"; cat $file|grep "$line"; done done I got some duplicated values in each LocalDescriptions.properties file[1], which maybe the suspicious points need to be looked at? [1] https://gist.github.com/gaol/1d40e5ef6c6eb0f7e2bd Best Regards -- Lin Gao Software Engineer JBoss by Red Hat ----- Original Message ----- > From: "Brian Stansberry" <brian.stansberry(a)redhat.com&gt; > To: wildfly-dev(a)lists.jboss.org > Sent: Tuesday, November 24, 2015 5:02:55 AM > Subject: [wildfly-dev] Best practices for management API text descriptions > > This thread is to flesh out some thinking about best practices for the > content of the free form text descriptions of the resources, attributes > and operations in the WildFly management model. Red Hat's user > experience team has been looking at some of the text in the admin > console, much of which comes from the server side management API > descriptions. As they start pinging subsystem authors looking for > improvements, I think it will be helpful if we use this thread to come > to some consensus around best practices. > > There is a lot of information provided by the server about the > management API, going well beyond free form text descriptions. I > encourage people to review [1] and particularly sections [2] and [3]. > Any management client that tries to read the text description of, say, > an attribute will automatically get the other descriptive data as well. > Type information, whether a value is required, legal values, affect on > the runtime of changing an attribute, etc. > > Because the full set of descriptive data is available to a tool whenever > the text is, IMHO it makes sense *in general* to avoid repeating > information in the free form text that is already available elsewhere in > the descriptive data[4], for a number of reasons: > > 1) Whether or not particular bits of info will be added to the free form > text will be inconsistent, depending on what an author chose to do. > > 2) The language quality of the free form text will vary widely. > > 3) The size of our metadata payloads is already a concern. Duplicating > data by putting it in free form text increases this problem. > > 4) Duplicating data leads to maintenance troubles when details change, > since now the information needs to be updated in two places. > > 5) People doing localization need to translate more text. > > Instead of duplicating data in the free form text, we're better off > looking into how our standard clients (admin console, CLI, JConsole > plugin) can best present the information present in the other descriptor > fields. For example, put a '*' next to required fields in a graphical > UI. (I think there's a HAL JIRA for that one!) > > In some cases the right answer for a UI is to show a chunk of text, e.g. > in a tooltip. But even there I think the best way to show standard info > is to append standardized text to the free form text provided by the > server. So, if some attribute "max-size" has > restart-required=all-services and the free form text for "max-size" > reads "The maximum number of threads in the pool", then the console > could generate a tool tip that reads: > > The maximum number of threads in the pool. > Servers must be reloaded for changes to take effect. > > I think this kind of approach can work well for the "nillable", > "expressions-allowed", "min", "max", "default", "alternatives", > "requires" and "restart-required" descriptors. > > For the "allowed" descriptor, the only reason to include the allowed > values in the free form text is if the meaning of the legal values isn't > clear and the free form text includes some explanation. Otherwise, a UI > can already use the "allowed" descriptor to show the legal values, e.g. > via a pull down in a GUI or tab completion in the CLI. > > I'm not advocating we go off on a major expedition to change our > existing text. I do however want to avoid us adhoc adding a lot of > duplicate text, unless we come to a consensus that that's the best approach. > > [1] > https://docs.jboss.org/author/display/WFLY10/Admin+Guide#AdminGuide-Descr... > > [2] > https://docs.jboss.org/author/display/WFLY10/Admin+Guide#AdminGuide-Descr... > > [3] > https://docs.jboss.org/author/display/WFLY10/Admin+Guide#AdminGuide-Arbit... > > > [4] For example, the "restart-required" descriptor on an attribute > indicates what must happen for a change to the attribute to take effect. > So including "The server must be reloaded for a change to take effect" > in the free form text is duplication. > > -- > Brian Stansberry > Senior Principal Software Engineer > JBoss by Red Hat > _______________________________________________ > wildfly-dev mailing list > wildfly-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/wildfly-dev >