Update README #433
Update README #433
Conversation
- Add introductory paragraph about CDK components and usage. - Move manual installation instructions to separate file; this is no longer on the typical user experience path.
MANUAL_INSTALLATION.md
Outdated
|
|
||
| You can either download the zip file from the | ||
| [Releases](http://github.com/awslabs/aws-cdk/releases) page on GitHub or if you | ||
| prefer, download them bits from S3 using the URL provided by our team. |
There was a problem hiding this comment.
Remove the S3 part, we will no longer publish to S3 after we go public
MANUAL_INSTALLATION.md
Outdated
| aws s3 cp <s3-url> ~/aws-cdk.zip | ||
| ``` | ||
|
|
||
| ## General Hints |
There was a problem hiding this comment.
Yeah, "hints" is maybe not the right word. But I want to give a couple of sentences of "goal" introduction for people who more or less understand what is going to happen, before moving to the a step-by-step-here-is-every-line-you-type style instructions.
Conceptually, what you're doing is very simple, but it might look complicated because of the giant list of instructions.
README.md
Outdated
| @@ -4,7 +4,11 @@ | |||
|
|
|||
| The **AWS Cloud Development Kit (AWS CDK)** is an infrastructure modeling framework that allows you to define your cloud resources using an imperative programming interface. The CDK is currently in developer preview. We look forward to community feedback and collaboration. | |||
|
|
|||
| ## Getting Started | |||
| You can use the CDK to define your cloud architecture in code, by composing and creating reusable cloud components called *constructs*. You build your application using the *AWS CDK Construct Library*, a set of classes that encompass all of AWS' services, and then use the *CDK Toolkit* command-line interface to run your program, convert your code to a CloudFormation template, and execute the deployment. Underneath it all is the *CDK Framework* which defines the APIs for the various components. | |||
There was a problem hiding this comment.
To be honest, this sentence is a bit long and convoluted, how about something like this:
Developers can use one of the supported programming languages to define reusable cloud components called constructs, which are composed together into Stacks and Apps. Apps are synthesized to AWS CloudFormation Templates and deployed to the AWS Cloud using the CDK Command Line Toolkit.
The CDK is shipped with a rich library of constructs called the AWS Construct Library, which includes constructs for all AWS services.
There was a problem hiding this comment.
...into Stacks and Apps. Apps are synthesized to...
As a new user reading this: "Ok, so what are Stacks?"
README.md
Outdated
| @@ -15,74 +19,25 @@ Make sure you have the following prerequisites installed: | |||
| * The development toolchain of the language you intend to use (TypeScript, | |||
There was a problem hiding this comment.
Remove the line about the development toolchain, it's completely unneeded
README.md
Outdated
| Add-Content -Path $PROFILE -Value '$env:Path = "$env:Path;$env:UserProfile\.cdk\node_modules\.bin"' | ||
| Set-ExecutionPolicy Unrestricted | ||
| & $PROFILE | ||
| npm install -g aws-cdk |
There was a problem hiding this comment.
This is not only for TypeScript.
I would also add a code snippet here until we have the screencast. Also, I would add one line before each command explaining what it does:
Something like:
Initialize an empty CDK project in one of the supported languages:
cdk init app --language typescript # or java
Define your cloud application in code:
<code snippet>
Build & deploy to the AWS Cloud:
cdk deploy
MANUAL_INSTALLATION.md
Outdated
|
|
||
| ## General Hints | ||
|
|
||
| We recommend you extract the package to `~/.cdk`. When using the manual installation |
There was a problem hiding this comment.
If I'm a new user and I read this, I think "Will something go wrong if I extract to somewhere else?" Maybe something like "Extract the package to a folder on your machine (in the examples, we extracted to ~/.cdk).
There was a problem hiding this comment.
Doesn't work. y-npm will only work if the files are in that location, if I'm not mistaken.
There was a problem hiding this comment.
No- y-npm searches relative to where it is installed in + from where it is invoked from. You can extract wherever you like... the CDK toolkit May have a couple of things that expect it to be in ~/.cdk but those can be overridden by setting CDK_HOME (but could be such toolkit stuff actually no longer exist at all)
README.md
Outdated
| @@ -4,7 +4,11 @@ | |||
|
|
|||
| The **AWS Cloud Development Kit (AWS CDK)** is an infrastructure modeling framework that allows you to define your cloud resources using an imperative programming interface. The CDK is currently in developer preview. We look forward to community feedback and collaboration. | |||
|
|
|||
| ## Getting Started | |||
| You can use the CDK to define your cloud architecture in code, by composing and creating reusable cloud components called *constructs*. You build your application using the *AWS CDK Construct Library*, a set of classes that encompass all of AWS' services, and then use the *CDK Toolkit* command-line interface to run your program, convert your code to a CloudFormation template, and execute the deployment. Underneath it all is the *CDK Framework* which defines the APIs for the various components. | |||
There was a problem hiding this comment.
...into Stacks and Apps. Apps are synthesized to...
As a new user reading this: "Ok, so what are Stacks?"
no longer on the typical user experience path.
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license.