Change some of the documentation wording #186
Conversation
|
Thank you. Could you explain the motivation behind these changes? |
|
As I read through the documentation, I didn't feel like the information was fully accurate or novice-friendly. I tried to define the flow of the reading a bit smoother. Please feel free to close this one if you think I made the documentation worst or took it towards a path that doesn't align with what you had in mind. |
|
Thanks. The thing is that this new version looks much more complex to me. For example it includes new concepts such as:
The vocabulary and details are also more precise but more complex, for example for comparison:
compared to the proposed replacement:
Since all of these concepts will be new to most PHP developers, and some will not be native english spearkers, I want to make it as accessible as possible. You version is more exact and I definitely acknowledge that I take some shortcuts ^^ But this is by design. I'd be interested though if you see things that can be simplified further (while still trying to be "correct"). In the meantime I'm sorry but I'll hold off merging it. However there are interesting parts, I'll mark them in the diff. If you have time to update the PR (or make another) to keep only those changes I'll merge it gladly! |
|
|
||
| ### SAM | ||
|
|
||
| SAM offers a simpler configuration format. This is what you are using if you use Bref (the `template.yaml` file). | ||
|
|
||
| The deployment process with SAM works like this: | ||
| The deployment process with SAM is divided into three steps: |
There was a problem hiding this comment.
👍 This change is great because it makes it more explicit that these steps follow each other.
We could still make it simpler I think, for example:
Deploying with SAM is done in 3 steps:
|
|
||
| That means you must **create a S3 bucket** to host your application code: | ||
|
|
||
| ```sh | ||
| aws s3 mb s3://<bucket-name> | ||
| ``` | ||
|
|
||
| The content of this bucket will be managed by AWS SAM. Do not use it in your application to store things like assets or uploaded files. | ||
| Note: The content of this bucket will be managed by AWS SAM. Do not use it in your application to store things like assets or uploaded files. |
|
|
||
| ### Deployment | ||
|
|
||
| Before deploying make sure your code is ready to be deployed. For example remove any development files from the project and install Composer dependencies optimized for production: | ||
| Before deploying, make sure your code is ready to be deployed. For example remove any development files from the project and install Composer dependencies optimized for production: |
|
|
||
| ## Deploying with SAM | ||
|
|
||
| ### Setup | ||
|
|
||
| > This step must be done only once per application. | ||
|
|
||
| To be deployed into AWS Lambda, your code must be uploaded on AWS S3. | ||
| AWS Lambda requires your code to be stored on a S3 bucket. |
There was a problem hiding this comment.
👍
Let's introduce the bucket concept in the next sentence, we can make it simpler here:
AWS Lambda requires your code to be stored on AWS S3.
No description provided.