[wildfly-dev] Best practices for management API text descriptions

[Lin Gao]

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 at redhat.com>
> To: wildfly-dev at 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-DescriptionoftheManagementModel
> 
> [2]
> https://docs.jboss.org/author/display/WFLY10/Admin+Guide#AdminGuide-DescriptionofanAttribute
> 
> [3]
> https://docs.jboss.org/author/display/WFLY10/Admin+Guide#AdminGuide-ArbitraryDescriptors
> 
> 
> [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 at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>