Update the aws-codepipeline package ReadMe.

packages/@aws-cdk/aws-codepipeline/README.md

@@ -1,29 +1,41 @@
-## AWS CodePipeline construct library
+## AWS CodePipeline Construct library
 
-Construct an empty pipeline:
+This library allows you to construct AWS CodePipelines.
+A Pipeline is modeled like other CDK Constructs:
+they form a tree, with Pipeline at the root.
+Stages then take a Pipeline as their parent,
+and finally Actions take a Stage as their parent.
+
+Example:
 
 ```ts
-const pipeline = new Pipeline(this, 'MyFirstPipeline');
+import codepipeline = require('@aws-cdk/aws-codepipeline');
+
+const pipeline = new codepipeline.Pipeline(this, 'MyFirstPipeline', {
+    pipelineName: 'MyFirstPipeline',
+});
+const stage = new codepipeline.Stage(pipeline, 'Source');
+new codepipeline.GithubSource(stage, 'GitHub Source', {
+    artifactName: 'SourceArtifact',
+    owner: 'awslabs',
+    repo: 'aws-cdk',
+    oauthToken: new SecretParameter(//...
+})
 ```
 
-All of the components of a pipeline are modeled as constructs.
+### Actions
 
-Append a stage to the pipeline:
+Actions are organized as follows.
 
-```ts
-const sourceStage = new Stage(pipeline, 'Source');
-```
+The most popular Actions for external integrations
+(like a GitHub source, a Jenkins build and test, etc.)
+are placed in this, `aws-codepipeline`, package.
 
-Add an action to a stage:
+The integrations with AWS services all live in their dedicated packages, so:
 
-```ts
-new codecommitPipeline.SourceAction(sourceStage, 'source', {
-    artifactName: 'MyPackageSourceArtifact',
-    repository: codecommit.RepositoryRef.import(this, 'MyExistingRepository', {
-        repositoryName: new codecommit.RepositoryName('MyExistingRepository'),
-    }),
-})
-```
+* [`aws-codecommit-codepipeline`](../aws-codecommit-codepipeline) contains the AWS CodeCommit source Action
+* [`aws-codebuild-codepipeline`](../aws-codebuild-codepipeline) contains the AWS CodeBuild build and test Actions
+* [`aws-lambda-codepipeline`](../aws-lambda-codepipeline) contains the AWS Lambda invoke Action
 
 ### Events