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

2017-05-16 Thread Monty Taylor 

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/

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/

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?
- 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.


Thanks!
Monty

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2017-05-16 Thread Qiming Teng 
On Tue, May 16, 2017 at 05:13:16PM -0500, Monty Taylor 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/
> 
> 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/
> 
> 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.

> - servers[].name - servers is a list, containing objects with a name
> field. Good or bad?

Good.

> - servers[].addresses.$network-name - addresses is an object and the
> keys of the object are the name of the network in question.

This is a little bit confusing but still understandable.

my $0.0002 

Qiming
> Thanks!
> Monty
 


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2017-05-17 Thread Chris Dent 

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__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2017-05-17 Thread Sean Dague 
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

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2017-05-17 Thread Joe Topjian 
On Tue, May 16, 2017 at 4:13 PM, Monty Taylor  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/
>
> 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/
>
> 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.


> - 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.

Thanks,
Joe
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2017-05-19 Thread Monty Taylor 

On 05/17/2017 10:14 AM, Joe Topjian wrote:



On Tue, May 16, 2017 at 4:13 PM, Monty Taylor mailto:mord...@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/


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/



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/

That adds  tags around the leaf element. so basically:

servers[].addresses.$network-name[].OS-EXT-IPS-MAC:mac_addr

becomes

servers[].addresses.$network-name[].**OS-EXT-IPS-MAC:mac_addr**

which I hope will ease any confusion when leaf elements have punctuation 
in their names - like OS-EXT-IPS-MAC:mac_addr


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2017-05-19 Thread Sean Dague 
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 > > 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/
>> 
>>
>> 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/
>>
>>
>> 
>>
>>
>> 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  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

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2017-05-19 Thread Joe Topjian 
On Fri, May 19, 2017 at 8:00 AM, Sean Dague  wrote:

> 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  >> > 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/
> >> 
> >>
> >> 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/
> >>
> >>
> >>  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  tags.


+1 on the  tags.
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev