Hi, Dave, Somesh,
Thanks for your feedback. Thanks for the help that you promised on this
task.
Hi, Dave,
Thanks for providing the Style Guide for the API Guides and some good
pointers on improving the API content. This is helpful.
Hi, Somesh,
Thanks for your willingness to help with the content.
I will use the information that you shared with me to create an efficient
plan for improving content for the 20 APIs that I listed in my earlier
email. Will get back to all of you with my plan for this task soon.
Regards,
Rajsekhar
On Mon, Aug 3, 2015 at 9:28 PM, Somesh Naidu <somesh.na...@citrix.com>
wrote:
> {should you be adding [DISCUSS] and/or [PROPOSAL] to the subject?}
>
> +1
>
> Definitely required. Improvements in description/function required for
> both the API call itself and associated parameters. I am willing to help
> with the content.
>
> Regards,
> Somesh
>
>
> -----Original Message-----
> From: Dave Dunaway [mailto:dave.duna...@gmail.com]
> Sent: Monday, August 03, 2015 9:24 AM
> To: us...@cloudstack.apache.org
> Cc: dev@cloudstack.apache.org
> Subject: Re: Improving API reference pages
>
> I would definitely say this is needed. A few calls need to specify "types"
> of which there is not description or they are poorly worded.
>
> If the API doc page could have comments... that would be good too. Let the
> community add examples or suggestions.
>
> However the real deal is to document the attributes and return values for
> each call. Show a basic call using curl. Describe what the call does (some
> have no description). Like what most other sites with API's do :)
>
> Here's a "style" guide for API documentation creation... it seems pretty
> good.
>
> http://blog.parse.com/learn/engineering/designing-great-api-docs/
>
> HTH
>
> dave.
>
>
>
> On Mon, Aug 3, 2015 at 5:37 AM, Rajsekhar K <rajsekharkpa...@gmail.com>
> wrote:
>
> > Hi, All,
> >
> > This is part of our effort to improve user experience of
> > Cloudstack/CloudPlatform API reference pages.
> >
> > Majority of the CloudStack/CloudPlatform API reference pages do not
> > adequately describe the usage of the parameters associated with them.
> Many
> > of these parameters contain only a single line description, which does
> not
> > really enhance the user's experience with these APIs.
> >
> > CloudPlatform had received a few documentation tickets on this, with
> > requests to improve the description, add information on the format, and
> an
> > example on how to use the parameter. One of the tickets was on the
> > *migrateto *parameter in the *migrateVirtualMachineWithVolume* API
> > reference page. We have improved the description of the *migrateto
> > *parameter
> > as follows:
> >
> > *Parameter*
> >
> > *Description*
> >
> > *Required*
> >
> > *migrateto*
> >
> > Storage to pool mapping. This parameter specifies the mapping between a
> > volume and a pool where you want to migrate that volume. Format of this
> > parameter:
> >
> >
> migrateto[volume-index].volume=<uuid>&migrateto[volume-index].pool=<uuid>Where,
> > [volume-index] indicates the index to identify the volume that you want
> to
> > migrate, volume=<uuid> indicates the UUID of the volume that you want to
> > migrate, and pool=<uuid> indicates the UUID of the pool where you want to
> > migrate the volume. Example:
> >
> >
> migrateto[0].volume=<71f43cd6-69b0-4d3b-9fbc-67f50963d60b>&migrateto[0].pool=<a382f181-3d2b-4413-b92d-b8931befa7e1>&migrateto[1].volume=<88de0173-55c0-4c1c-a269-83d0279eeedf>&migrateto[1].pool=<95d6e97c-6766-4d67-9a30-c449c15011d1>&migrateto[2].volume=<1b331390-59f2-4796-9993-bf11c6e76225>&migrateto[2].pool=<41fdb564-9d3b-447d-88ed-7628f7640cbc>
> >
> > False
> >
> > (This will be updated in the *migrateVirtualMachineWithVolume* API
> > reference page of CloudStack soon.)
> >
> > I think I can take this as a base and improve the descriptions of the
> > parameters in the CloudStack/Cloudplatform API reference pages. As an
> > initial step, I have identified the following 20 API functions and I am
> > planning to improve the description of the parameters in their reference
> > pages:
> >
> >
> > -
> > *listAccounts *
> > -
> > *listCapacity *
> > -
> > *listLoadBalancerRules *
> > -
> > *listNetworks *
> > -
> > *listPublicIpAddresses *
> > -
> > *listSnapshots *
> > -
> > *listTemplates *
> > -
> > *listVirtualMachines *
> > -
> > *listVolumes *
> > -
> > *listZones *
> > -
> > *stopVirtualMachine *
> > -
> > *associateIPAddress *
> > -
> > *attachVolume *
> > -
> > *createSnapshot *
> > -
> > *startVirtualMachine *
> > -
> > *deployVirtualMachine *
> > -
> > *migrateVirtualMachineWithVolume *
> > -
> > *login *
> > -
> > *logout *
> > - *updateVirtualMachine*
> >
> > Could you please provide your thoughts on this suggestion? Also, please
> let
> > me know how you can help/contribute in this effort.
> >
> > Regards,
> > Rajsekhar
> >
>
