[wildfly-dev] Best practices for management API text descriptions
brian.stansberry at redhat.com
Mon Nov 23 16:02:55 EST 2015
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  and particularly sections  and .
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, 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.
 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.
Senior Principal Software Engineer
JBoss by Red Hat
More information about the wildfly-dev