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

[Brian Stansberry]

Scanning quickly, those all look fine except for

https://gist.github.com/gaol/1d40e5ef6c6eb0f7e2bd#file-wildfly-core-duplicate-description-items-L62

https://gist.github.com/gaol/1d40e5ef6c6eb0f7e2bd#file-wildfly-core-duplicate-description-items-L70

For those two the 'fallback-loader' description sounds odd.

https://gist.github.com/gaol/1d40e5ef6c6eb0f7e2bd#file-wildfly-core-duplicate-description-items-L78

I'm not sure if those are right or wrong.

It's normal for the same text to occur for different attributes, 
particularly if they have the same attribute name but a different prefix.

On 12/1/15 1:03 AM, Lin Gao wrote:
> 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
>>


-- 
Brian Stansberry
Senior Principal Software Engineer
JBoss by Red Hat