[openstack-dev] [horizon][api][docs] Feedback requested on proposed formatting change to API docs
joe at topjian.net
Fri May 19 15:00:35 UTC 2017
On Fri, May 19, 2017 at 8:00 AM, Sean Dague <sean at dague.net> 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 <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-
> >> <http://docs-draft.openstack.org/55/464255/5/check/gate-
> >> 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
> >> 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-
> is actually the revision with the <strong> tags.
+1 on the <strong> tags.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the OpenStack-dev