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

Sean Dague sean at dague.net
Wed May 17 12:16:06 UTC 2017


On 05/17/2017 07:40 AM, Chris Dent wrote:
> 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.

The visually greppable part concerns me as well.

I wonder if a dedicated parent column would make sense? Like "Contained In"

| addresses | servers[] | ...............
| addr      | servers[].addresses.$network-name | ...........

Especially as these things get to
"servers[].addresses.$network-name[].OS-EXT-IPS-MAC:type" they are
wrapping in the name field, which makes them even harder to find.

Maybe figure out the right visual first, then work backwards on a
structure that can build it. But, like I said in IRC, I'm *so* steeped
in all of this, I definitely don't trust my judgement in what's good for
folks that don't have half the code in their head.

	-Sean

-- 
Sean Dague
http://dague.net



More information about the OpenStack-dev mailing list