Open Stack

On 05/19/2017 08:36 AM, Monty Taylor wrote:
> On 05/17/2017 10:14 AM, Joe Topjian wrote:
>>
>>
>> On Tue, May 16, 2017 at 4:13 PM, Monty Taylor <mordred at inaugust.com
>> <mailto:mordred at inaugust.com>> wrote:
>>
>>     Hey all!
>>
>>     I read the API docs A LOT. (thank you to all of you who have worked
>>     on writing them)
>>
>>     As I do, a gotcha I hit up against a non-zero amount is mapping the
>>     descriptions of the response parameters to the form of the response
>>     itself. Most of the time there is a top level parameter under which
>>     either an object or a list resides, but the description lists list
>>     the top level and the sub-parameters as siblings.
>>
>>     So I wrote a patch to os-api-ref taking a stab at providing a way to
>>     show things a little differently:
>>
>>     https://review.openstack.org/#/c/464255/
>>     <https://review.openstack.org/#/c/464255/>
>>
>>     You can see the output here:
>>
>>    
>> http://docs-draft.openstack.org/55/464255/5/check/gate-nova-api-ref-src/f02b170//api-ref/build/html/
>>
>>    
>> <http://docs-draft.openstack.org/55/464255/5/check/gate-nova-api-ref-src/f02b170//api-ref/build/html/>
>>
>>
>>     If you go expand either the GET / or the GET /servers/details
>>     sections and go to look at their Response sections, you can see it
>>     in action.
>>
>>     We'd like some feedback on impact from humans who read the API docs
>>     decently regularly...
>>
>>     The questions:
>>
>>     - Does this help, hurt, no difference?
>>
>>
>> It helps. It seems noisy at first glance, but the information being
>> denoted is important. It's one of those situations where once you start
>> reading deeper into the information, this kind of markup makes the API
>> more understandable more quickly.
> 
> Awesome. Thanks!
> 
>>     - 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.
>>
>>
>> Again, these seem noisy at first, but having parsed complex paths,
>> especially the above address info, by dumping variables too many times,
>> I really appreciate the above syntax.
>>
>> Going even further:
>>
>> servers[].addresses.$network-name[].OS-EXT-IPS-MAC:mac_addr
>>
>> looks a mess, but I can see how exactly to navigate to the leaf as well
>> as understand what types make up the path. Being able to succinctly
>> (relatively/subjectively speaking) describe something like the above is
>> very helpful. This definitely gets my support.
> 
> Sweet. thanks for the feedback! I just pushed up a new rev yesterday
> based on some feedback from Anne:
> 
> http://docs-draft.openstack.org/55/464255/5/check/gate-nova-api-ref-src/f02b170//api-ref/build/html/

http://docs-draft.openstack.org/55/464255/7/check/gate-nova-api-ref-src/88a33cc//api-ref/build/html/
is actually the revision with the <strong> tags.

I think that satisfies my concerns on visual skimming. +2 on moving
forward conceptually. Will leave any other comments in the review.

	-Sean

-- 
Sean Dague
http://dague.net