Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Replace "cdk init" with better getting started instructions #219

Closed
eladb opened this issue Jul 2, 2018 · 0 comments · Fixed by #245
Closed

Replace "cdk init" with better getting started instructions #219

eladb opened this issue Jul 2, 2018 · 0 comments · Fixed by #245

Comments

@eladb
Copy link
Contributor

eladb commented Jul 2, 2018

We need to get rid of "cdk-init". I've always been averse to project templating systems, and feedback from one of our beta customers had increased my suspicion that we took the wrong turn. The problem with project templating is that they encourage developers to not understand what's going on, which means that now when they want to evolve their solution, they get stuck and need more spoon-feeding. The other problem, which is even worse, is that it gives us a way to be lazy about designing a good product that is easy to use and iterate on without crutches.

I believe that without "cdk-init" (or at least not rely on cdk-init for our getting started docs), we will be forced to think very hard about every part of the story and reduce as much boilerplate as possible, so to make sure it can be concisely and simply described in our docs. This is a great forcing function for us, and eventually cause us to build a better product. It will also make sure that users are not blindly using our templates without understanding what's going on.

For example, to define a javascript-based CDK project, all you need to do is:

$ npm init -y # creates package.json
$ npm i @aws-cdk/core @aws-cdk/sns
$ edit index.js
<app boilerplate, which we should GET RID OF>
$ edit cdk.json
<we can get rid of that too by auto-discovering package.json>
$ cdk synth
<works!>

This is a very small set of instructions and if we actually spend the time and think hard about the boilerplate here, I believe we can get rid of most of it (namely, the App boilerplate and cdk.json). By walking developers through the details of creating a new project, it will give us an opportunity to explain what is each step.

Here's what I propose: let's start by modifying our getting started documentation not to use "cdk-init". I am willing to take a stab at it. I also have an idea on how to get rid of the cdk.json and app boilerplate (#216).

Going forward, when the project is a bit more mature, we can offer templates that use something like cookiecutter or even just put some sample projects in GitHub and send people there if they want a copy & paste experience.

eladb pushed a commit that referenced this issue Jul 8, 2018
Add getting started and welcome in Java (and JavaScript).

Rewrite "Getting Started" to detail the process of defining CDK apps
without using `cdk init`. This is in order to improve the understanding
of users when they onboard the CDK, which fixes #219.

Fix TOC to include only two layers deep which fixes #129.
@eladb eladb closed this as completed in #245 Jul 9, 2018
eladb pushed a commit that referenced this issue Jul 9, 2018
Add getting started and welcome in Java (and JavaScript).

* Rewrite "Getting Started" to detail the process of defining CDK apps
without using `cdk init`. This is in order to improve the understanding
of users when they onboard the CDK, which fixes #219.
* Fix TOC to include only two layers deep which fixes #129.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant