Improving descriptions in the API reference pages

[Rajsekhar K <ra...@gmail.com>]

Hi, All,

This is part of our effort to improve user experience of Cloudstack API
reference pages.

Majority of the CloudStack 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.

As part of this content improvement effort, I need to improve the
description, add information on the format, and an example on how to use
the parameter. Please find attached the improved content for the
"migrateto" parameter in the 'migrateVirtualMachineWithVolume' API
reference page as an example.

I think I can take the description for the "migrateto" parameter as a base
and improve the descriptions of the parameters in the CloudStack 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
available 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

Re: Improving descriptions in the API reference pages

[Daan Hoogland <da...@gmail.com>]

I don't think there is a guy named Nick Brody actually showing his
disinterest here.
@nick if you are there this is a turing test. You exist?

On Mon, Aug 3, 2015 at 12:57 PM, Nick Brody <ni...@gmail.com> wrote:
> Whatever
>
> On Mon, Aug 3, 2015 at 3:28 AM, Rajsekhar K <ra...@gmail.com>
> wrote:
>
>> Hi, All,
>>
>> This is part of our effort to improve user experience of Cloudstack API
>> reference pages.
>>
>> Majority of the CloudStack 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.
>>
>> As part of this content improvement effort, I need to improve the
>> description, add information on the format, and an example on how to use
>> the parameter. Please find attached the improved content for the
>> "migrateto" parameter in the 'migrateVirtualMachineWithVolume' API
>> reference page as an example.
>>
>> I think I can take the description for the "migrateto" parameter as a base
>> and improve the descriptions of the parameters in the CloudStack 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
>> available 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
>>



-- 
Daan

Re: Improving descriptions in the API reference pages

[Daan Hoogland <da...@gmail.com>]

Erik, Nick Brody is an alias from some american soap or something, so
it is probably a temporary account that's been hacked.

On Mon, Aug 3, 2015 at 1:48 PM, Erik Weber <te...@gmail.com> wrote:
> Hi Nick,
>
> If that is indeed your name, and not an alias.
>
> This is not the first time you have answered with short, at times also
> provocative, unnecessary messages.
> I, and probably more, would appreciate if you held these kind of messages
> to yourself, instead of polluting this list with garbage.
>
> --
> Erik
>
> On Mon, Aug 3, 2015 at 12:57 PM, Nick Brody <ni...@gmail.com> wrote:
>
>> Whatever
>>
>> On Mon, Aug 3, 2015 at 3:28 AM, Rajsekhar K <ra...@gmail.com>
>> wrote:
>>
>> > Hi, All,
>> >
>> > This is part of our effort to improve user experience of Cloudstack API
>> > reference pages.
>> >
>> > Majority of the CloudStack 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.
>> >
>> > As part of this content improvement effort, I need to improve the
>> > description, add information on the format, and an example on how to use
>> > the parameter. Please find attached the improved content for the
>> > "migrateto" parameter in the 'migrateVirtualMachineWithVolume' API
>> > reference page as an example.
>> >
>> > I think I can take the description for the "migrateto" parameter as a
>> base
>> > and improve the descriptions of the parameters in the CloudStack 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
>> > available 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
>> >
>>



-- 
Daan

Re: Improving descriptions in the API reference pages

[Erik Weber <te...@gmail.com>]

Hi Nick,

If that is indeed your name, and not an alias.

This is not the first time you have answered with short, at times also
provocative, unnecessary messages.
I, and probably more, would appreciate if you held these kind of messages
to yourself, instead of polluting this list with garbage.

-- 
Erik

On Mon, Aug 3, 2015 at 12:57 PM, Nick Brody <ni...@gmail.com> wrote:

> Whatever
>
> On Mon, Aug 3, 2015 at 3:28 AM, Rajsekhar K <ra...@gmail.com>
> wrote:
>
> > Hi, All,
> >
> > This is part of our effort to improve user experience of Cloudstack API
> > reference pages.
> >
> > Majority of the CloudStack 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.
> >
> > As part of this content improvement effort, I need to improve the
> > description, add information on the format, and an example on how to use
> > the parameter. Please find attached the improved content for the
> > "migrateto" parameter in the 'migrateVirtualMachineWithVolume' API
> > reference page as an example.
> >
> > I think I can take the description for the "migrateto" parameter as a
> base
> > and improve the descriptions of the parameters in the CloudStack 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
> > available 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
> >
>

Re: Improving descriptions in the API reference pages

[Nick Brody <ni...@gmail.com>]

Whatever

On Mon, Aug 3, 2015 at 3:28 AM, Rajsekhar K <ra...@gmail.com>
wrote:

> Hi, All,
>
> This is part of our effort to improve user experience of Cloudstack API
> reference pages.
>
> Majority of the CloudStack 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.
>
> As part of this content improvement effort, I need to improve the
> description, add information on the format, and an example on how to use
> the parameter. Please find attached the improved content for the
> "migrateto" parameter in the 'migrateVirtualMachineWithVolume' API
> reference page as an example.
>
> I think I can take the description for the "migrateto" parameter as a base
> and improve the descriptions of the parameters in the CloudStack 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
> available 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
>