[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