[openstack-dev] [horizon][api][docs] Feedback requested on proposed formatting change to API docs

Chris Dent 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 mailing list