[openstack-dev] [horizon][api][docs] Feedback requested on proposed formatting change to API docs
cdent+os at anticdent.org
Wed May 17 11:40:48 UTC 2017
On Tue, 16 May 2017, Monty Taylor wrote:
> The questions:
> - Does this help, hurt, no difference?
> - servers.name - servers is a list, containing objects with a name field.
> Good or bad?
> - servers.addresses.$network-name - addresses is an object and the keys of
> the object are the name of the network in question.
I sympathize with the motivation, but for me these don't help: they
add noise (more symbols) and require me to understand yet more syntax.
This is probably because I tend to look at the representations of the
request or response, see a key name and wonder "what is this?" and
then look for it in the table, not the other way round. Thus I want
the key name to be visually greppable without extra goo.
I suspect, however, that I'm not representative of the important
audience and feedback from people who are "real users" should be
prioritized way higher than mine.
Chris Dent ┬──┬◡ﾉ(° -°ﾉ) https://anticdent.org/
freenode: cdent tw: @anticdent
More information about the OpenStack-dev