feat(concepts): "scope" instead of "parent" #1

eladb · 2019-01-08T15:14:14Z

Shift the conceptual mental model to talk about the scope
hierarchy instead of a tree with parents and children.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Shift the conceptual mental model to talk about the scope hierarchy instead of a tree with parents and children. See aws/aws-cdk#1444

sam-goodwin

Looks good, i love the decision to call the parents scopes.

sam-goodwin · 2019-01-08T15:36:03Z

doc_source/constructs.md

+
+The low-level resources are automatically generated from the [AWS CloudFormation Resource Types Reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html). Low-level constructs are named `CfnXyz` (where "Xyz" represents the name of the resource) and provide direct, one-to-one access to how a resource is synthesized in the CloudFormation template produced by your CDK app. Using low-level resources require explicit configuration of all resource properties, IAM policies and requires deep understanding of the details.
+
+High-level resources are hand-written by AWS and offer a rich, intent-based API for using AWS services. They offer the same functionality as the low-level resources but encode much of the details, boilerplate and glue-logic required in order to use AWS. High-level resources offer convenient defaults and additional knowledge about the inner workings of the AWS resources they represent\. In general, you will be able to express your intent without worrying about the details too much, and the correct resources and configuration will automatically be defined for you\.  


Thought-provoking example such as granting access/enabling encryption etc. ?

Let me noodle this.

sam-goodwin · 2019-01-08T16:19:23Z

doc_source/constructs.md

 });
 ```

-Avoid specifying physical names\. Instead, let AWS CloudFormation generate names for you\. Use attributes, such as `bucket.bucketName`, to discover the generated names\.
+In general it's recommended to avoid specifying physical names\. Instead, let AWS CloudFormation generate names for you\. Use attributes, such as `bucket.bucketName`, to discover the generated names\.


Should we mention how discovered names maps to cloud formation functions?

Maybe in the CloudFormation topic?

sam-goodwin · 2019-01-08T18:00:49Z

doc_source/constructs.md

 ```

-In almost all cases, you should pass the keyword `this` for the `parent` argument, because you will generally initialize new constructs in the context of the parent construct\. Any descriptive string will do for the `name` argument, and an in\-line object for the set of properties\.
+The first argument to every construct is always the scope in which it is created, and will almost always be simply `this` because most constructs will be defined within the current scope.


Perhaps clarify that 'current scope' means within the constructor or method of another construct. Might be confusing to new-comers without sample code. Or expand the example to include the outer scope?

We don't need to explain scope. It's a fundamental programming concept.

I kind of agree with @sam-goodwin - maybe we could say something like "...defined within the current scope, which is normally the initializer (constructor) or a method of some construct defined in your app".

Something like that...

It is a fundamental programming concept, but it is ambiguous in this context since we are just now introducing them to the CDK's implementation of scopes. For example, will a novice understand that the scope is also a construct?

sam-goodwin · 2019-01-08T19:09:52Z

doc_source/constructs.md


-```
+Scopes enable constructs to be composed together to form higher-level abstractions by enabling the framework to group them together into logical units, allocate globally unique identifiers and allow them to consult __context information__ such as the region in which it is going to be deployed into, which AZs are available for my account, etc.


Introduce the scope hierarchy? You haven't described how they are grouped together, only implied it.

I added an earlier explanation.

sam-goodwin · 2019-01-08T19:16:28Z

doc_source/constructs.md

 });
 ```

-**Note**  
-Associating the construct to its parent as part of initialization is necessary because the construct occasionally needs contextual information from its parent, such as to which the region the stack is deployed\.
+The `construct.node` property can be used to interact with the construct's node representation:


You're introducing the concept of a 'node' before explicitly describing the tree.

I've reworded the intro.

sam-goodwin · 2019-01-08T19:23:32Z

doc_source/constructs.md


-The AWS CDK includes two different levels of constructs:
+This composition of constructs also means you can easily create sharable constructs, and make changes to any construct and have those changes available to consumers as shared class libraries\.


Maybe you should briefly define the 'scope hierarchy'/'construct tree' here to explain the encapsulation and composability. Having the High/Low level explanation in between seems out of order to me.

I've added some more explanatory text.

sam-goodwin · 2019-01-08T19:26:32Z

doc_source/constructs.md


-## Construct Names<a name="constructs_EVER"></a>
+Every construct in a CDK app must have an **id** unique within the scope in which the construct is defined. IDs are used to find constructs in the construct hierarchy, and to allocate logical IDs so that AWS CloudFormation can keep track of the generated resources\.


First mention of the hierarchy is here.

Scope and hierarchy are fundamental concepts.

They still need to be explained in the context of the CDK in my mind.

Doug-AWS · 2019-01-08T20:37:00Z

I've incorporated the comments into the docs and will refresh shortly.

Doug-AWS · 2019-01-08T21:06:55Z

As soon as a release with 1444 is published, I'll update the docs.

eladb · 2019-01-08T21:10:08Z

@Doug-AWS can you please make sure you also incorporate @sam-goodwin's comments?

Doug-AWS · 2019-01-09T19:12:05Z

Yes, I've got most of them incorporated.

feat(concepts): "scope" instead of "parent"

e827083

Shift the conceptual mental model to talk about the scope hierarchy instead of a tree with parents and children. See aws/aws-cdk#1444

sam-goodwin reviewed Jan 8, 2019

View reviewed changes

Doug-AWS closed this Jan 8, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(concepts): "scope" instead of "parent" #1

feat(concepts): "scope" instead of "parent" #1

eladb commented Jan 8, 2019

sam-goodwin left a comment

sam-goodwin Jan 8, 2019

Doug-AWS Jan 8, 2019

sam-goodwin Jan 8, 2019

Doug-AWS Jan 8, 2019

sam-goodwin Jan 8, 2019

Doug-AWS Jan 8, 2019

eladb Jan 8, 2019

sam-goodwin Jan 8, 2019

sam-goodwin Jan 8, 2019

Doug-AWS Jan 8, 2019

sam-goodwin Jan 8, 2019

Doug-AWS Jan 8, 2019

sam-goodwin Jan 8, 2019

Doug-AWS Jan 8, 2019

sam-goodwin Jan 8, 2019

Doug-AWS Jan 8, 2019

eladb Jan 8, 2019

Doug-AWS commented Jan 8, 2019

Doug-AWS commented Jan 8, 2019

eladb commented Jan 8, 2019

Doug-AWS commented Jan 9, 2019


		The low-level resources are automatically generated from the [AWS CloudFormation Resource Types Reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html). Low-level constructs are named `CfnXyz` (where "Xyz" represents the name of the resource) and provide direct, one-to-one access to how a resource is synthesized in the CloudFormation template produced by your CDK app. Using low-level resources require explicit configuration of all resource properties, IAM policies and requires deep understanding of the details.

		High-level resources are hand-written by AWS and offer a rich, intent-based API for using AWS services. They offer the same functionality as the low-level resources but encode much of the details, boilerplate and glue-logic required in order to use AWS. High-level resources offer convenient defaults and additional knowledge about the inner workings of the AWS resources they represent\. In general, you will be able to express your intent without worrying about the details too much, and the correct resources and configuration will automatically be defined for you\.


		```
		Scopes enable constructs to be composed together to form higher-level abstractions by enabling the framework to group them together into logical units, allocate globally unique identifiers and allow them to consult __context information__ such as the region in which it is going to be deployed into, which AZs are available for my account, etc.


		The AWS CDK includes two different levels of constructs:
		This composition of constructs also means you can easily create sharable constructs, and make changes to any construct and have those changes available to consumers as shared class libraries\.


		## Construct Names<a name="constructs_EVER"></a>
		Every construct in a CDK app must have an id unique within the scope in which the construct is defined. IDs are used to find constructs in the construct hierarchy, and to allocate logical IDs so that AWS CloudFormation can keep track of the generated resources\.

feat(concepts): "scope" instead of "parent" #1

feat(concepts): "scope" instead of "parent" #1

Conversation

eladb commented Jan 8, 2019

sam-goodwin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Doug-AWS commented Jan 8, 2019

Doug-AWS commented Jan 8, 2019

eladb commented Jan 8, 2019

Doug-AWS commented Jan 9, 2019