[
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
