Documentation updates for public developer preview #436
Conversation
eladb
commented
Jul 30, 2018
eladb
commented
- Remove checked-in theme and install through requirements.txt
- Modify sidebar to read "AWS Cloud Development Kit"
- Fix a few bad module links
- Add installation instructions to "getting started"
- Remove y-npm and local maven repo information from "getting started"
- Changed "welcome" to be "index" and embedded a hidden toc there.
- Added some details about the AWS Construct Library
- Renamed "reference" to "aws-construct-lib"
- Renamed "advanced" to "cloudformation"
- Removed beta reference
- Updated Welcome page
- Moved "welcome" to "index".
- Merged "version reporting" with "tools"
* Remove checked-in theme and install through requirements.txt * Modify sidebar to read "AWS Cloud Development Kit" * Fix a few bad module links * Add installation instructions to "getting started" * Remove y-npm and local maven repo information from "getting started" * Changed "welcome" to be "index" and embedded a hidden toc there. * Added some details about the AWS Construct Library * Renamed "reference" to "aws-construct-lib" * Renamed "advanced" to "cloudformation" * Removed beta reference * Updated Welcome page * Moved "welcome" to "index". * Merged "version reporting" with "tools"
| modules based on the AWS service the resource belongs to. For example, the | ||
| :py:mod:`@aws-cdk/aws-ec2` module includes the `@aws-cdk/aws-ec2.VpcNetwork` | ||
| construct which makes it easy to define an `Amazon VPC | ||
| <https://aws.amazon.com/vpc>`_ in your CDK app. |
There was a problem hiding this comment.
Is the _ there intentional?
There was a problem hiding this comment.
Yes, that's how links are represented in rst apparently...
| policy will automatically be modified to allow the specific topic to invoke the | ||
| function. | ||
|
|
||
| Furthermore, most AWS Constructs expose ``grantXxx`` methods which allow |
There was a problem hiding this comment.
I don't like the looks of grantXxx - somehow I think I'll prefer grant~ or grant*. Particularly since there are examples right after. I'm not going to hold a grudge if you disagree, though.
| Event-driven APIs | ||
| ------------------ | ||
|
|
||
| Many of the AWS constructs include ``onXxx`` methods which can be used to react |
| For more information see the :doc:`refs/_aws-cdk_aws-cloudwatch` and :doc:`refs/_aws-cdk_aws-events` | ||
| documentation. | ||
|
|
||
| Security Groups |
There was a problem hiding this comment.
One thing that bothers me here is that parts of the value of the API (to me) is that people don't have to reason about "Security Groups", because they're scary mythical animals that are had to tamed, and always remain a little savage (so they bite without warning). Anchoring the doc on that name feels like we're asking people to know about the things we'd ideally want to isolate them from.
There was a problem hiding this comment.
I agree in general but we decided that we are going to align to the service semantics, even if the terminology is confusing, in order to improve discoverability and ability of people to map CDK concepts to existing the AWS knowledge base. @rix0rrr and I discussed that we will change the names of the classes to reflect that as well, but for now, I wanted to call out that the "connections programming model" is about security groups.
Added a more explicit ref
packages/aws-cdk-docs/src/conf.py
Outdated
| project = u'User Guide' | ||
| project_desc = u'User Guide' | ||
| project = u'AWS Cloud Development Kit' | ||
| project_desc = u'AWS Cloud Development Kit' |
There was a problem hiding this comment.
Not liking that project_desc === project.
| Prerequisites | ||
| ============= | ||
|
|
||
| `Node.js (>= 8.11.x) <https://nodejs.org/en/download>`_ - required for the |
There was a problem hiding this comment.
Do we have reasons to suggest people use a node that isn't on the 10.0.0 tree? I'm thinking now may be the chance to just update our requirements... And live in the futuristic present?
There was a problem hiding this comment.
It's a good idea to specify the minimum version required. Also 8.11.x is the LTS version of node, which means many people still use it, so we should make sure we at least support that.
There was a problem hiding this comment.
That makes sense to me. In any case, I do appreciate it being >= 8.11.x and not ^8.11.x.
packages/aws-cdk-docs/src/index.rst
Outdated
|
|
||
| * `AWS Developer blog <https://aws.amazon.com/blogs/developer/>`_ | ||
| * `GitHub repository <https://github.com/awslabs/aws-cdk>`_ | ||
|
|
There was a problem hiding this comment.
This blank line makes the list of things below look like it's incorrectly indented further down; when it isn't. Would remove (or does RST mandate it?)
* Revert reference to "Reference" * Some more modifications to "Welcome" * Added screencast to "Welcome"
