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

[Brian Stansberry]

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