incubator-cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Jessica Tomechak (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (CLOUDSTACK-464) Regression in AWSAPI docs, entire sections removed
Date Fri, 16 Nov 2012 06:58:12 GMT

    [ https://issues.apache.org/jira/browse/CLOUDSTACK-464?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13498644#comment-13498644
] 

Jessica Tomechak commented on CLOUDSTACK-464:
---------------------------------------------

Sebastien, thanks for your kind information to let me know of the proper procedure. I'm sorry
to have missed a step through not realizing that was required. I also did not realize you
were setting out to rewrite the sections at the time of your original review request, or I
would have looked more closely and provided comments in a more timely way. I thought you were
only doing the conversion to XML. Again, I'm sorry for that misunderstanding.

To respond for requests I have received for detailed information about each issue that I saw
in Sebastien's copy, here are the issues one by one.

I am providing the following detailed comments at Sebastien's and David N's request.

The files aws-ec2-configuration.xml and aws-ec2-requirements.xml mostly rephrased the information
that was already in the previous (CloudPlatform 3.0.3) version of the same doc, in a way that
was less grammatical and less clear. The version I created is basically a copy-edit of these
files, except for the following items: aws-ec2-configuration.xml added an API call example,
which looked fine; however it contained a reference to port 8096, which I have been asked
in the past to remove from docs for security reasons. This file also added some screen shots
which seemed to refer to images that were not checked in.

In aws-ec2-introduction.xml, I removed references to REST because I believed that REST was
not working, and should not be documented. This was based on information from Prachi and Likitha,
who coded the feature. When I checked with them, they referred to the feature as "quite broken".
Also, I did not see the feature in the 4.0 feature list on the Apache wiki. Sebastien and
David have since said they tested the REST interface and it worked for them, so there is some
disconnect here.

There were a couple of references to plans for the future. In aws-ec2-introduction, the sentence
starting "Expect ... in new releases" refers to the future, and similarly in awd-ec2-requirements,
the sentence "Effort is underway...". In my experience, it is a tech docs best practice to
record what is currently available rather than talking about future developments (which might
not materialize). Therefore I removed this text.

In aws-ec2-supported-commands.xml, I removed the headers above the tables, since they were
redundant with the table titles.

In aws-ec2-timeouts.xml, I added the Timeouts section, which was present in the previous version
of these docs and omitted from Sebastien's commit.

In aws-interface-compatibility.xml, I changed the title of the section from "AWS Interface
Guide" to "AWS Interface Compatibility," since the word "Guide" is usually used in a book
title, not a section that might be reused in several different books.

In aws-ec2-user-setup.xml, again the same information from the previous (3.0.3) version was
restated in a way that didn't seem more clear. Changes I made in this file were just copy-editing.
Also, I have recently learned that the user registration step is not required for users of
the REST interface, so if REST is re-introduced to the document, then it should be noted in
this section that this step can be skipped by REST users.

In the same file, some steps were omitted, such as where to download the cloudstack-aws-api-register
script and which values to substitute in the command.

In case it is necessary to provide an example of what is meant by "less clear", see the following:

Text from previous version (CloudStack 3.0.3):
"The user follows these steps:

1. Obtain the following by looking in the UI, using the API, or asking the cloud administrator:


* The CloudStack server's publicly available DNS name or IP address
* The user account's API key and Secret key"

This was changed to the following in Sebastien's version:

"To register, a user needs to: 

* Obtain his API key and his secret key as well as the DNS name or IP address of the CloudStack
server. Obtaining the keys can be done by asking the CloudStack administrator or by using
the GUI or via the  API."

Aside from the problematic use of "his," this creates a run-on sentence, and mixes several
items together rather than providing a scannable checklist.
                
> Regression in AWSAPI docs, entire sections removed
> --------------------------------------------------
>
>                 Key: CLOUDSTACK-464
>                 URL: https://issues.apache.org/jira/browse/CLOUDSTACK-464
>             Project: CloudStack
>          Issue Type: Bug
>          Components: Doc
>    Affects Versions: 4.0.0, 4.1.0
>            Reporter: sebastien goasguen
>            Assignee: Jessica Tomechak
>
> Commit 22b5c0cddd798829788b4e630b8ae77b81a05c2f on 10/17:
> Overwrites some of the documentation contributed previously on the
> AWSAPI. The commit introduces a few errors (e.g mention of CloudPlatform ) and overwrites
additional
> documentation submitted by me and committed on Sept 23rd By D. Nalley with commit:  56b4ac184f712f54868af83b5e8110af93b72e83

> While the commit does correct some typos, it basically reverts to the old documentation
which I had worked on towards improvement.

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira

Mime
View raw message