docs(tutorial): add new tutorial covering core features

[mploski]

#580

Description of changes:

Expanding Readme.md file with new Quickstart section
Checklist

• Meet tenets criteria
• Update tests
• Update docs
• PR title follows conventional commit semantics

Breaking change checklist

RFC issue #:

• Migration process documented
• Implement warnings (if it can live side by side)

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

---

View rendered README.md

[boring-cyborg]

Thanks a lot for your first contribution! Please check out our contributing guidelines and don't hesitate to ask whatever you need.

[DanyC97]

@mploski thanks for looking into this, do you have any thoughts/ have you considered how this new block will compare with https://github.com/aws-samples/cookiecutter-aws-sam-python which is also in the current Readme file?

where i'm coming from is:

As a new user i should have a single place where i can go and see an abundance of examples (in various phases of complexity starting from simple one to more like real projects) so it can be easy and confusion free.

[mploski]

@mploski thanks for looking into this, do you have any thoughts/ have you considered how this new block will compare with https://github.com/aws-samples/cookiecutter-aws-sam-python which is also in the current Readme file?

where i'm coming from is:

As a new user i should have a single place where i can go and see an abundance of examples (in various phases of complexity starting from simple one to more like real projects) so it can be easy and confusion free.

@DanyC97 Thanks for the valid suggestion. I will adjust my PR to use cookiecutter example.

[codecov-commenter]

Codecov Report

Merging #769 (e5e23d1) into develop (24ab726) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff            @@
##           develop     #769   +/-   ##
========================================
  Coverage    99.96%   99.96%           
========================================
  Files          119      119           
  Lines         5320     5320           
  Branches       613      613           
========================================
  Hits          5318     5318           
  Partials         2        2           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 24ab726...e5e23d1. Read the comment docs.

[heitorlessa]

Thanks a lot @DanyC97 for helping us improve, and @mploski for taking this head on!

A few tips:

• Tracing instead of X-Ray Tracing
• Break some paragraphs so it’s easier to read
• Make use of Admonitions to add banners like Tips, Info, etc.
• EMF and Log Code snippet is a single line instead of being multi-line
• Share ideas on what customers could do besides what’s being explained - take the opportunity to teach customers tips on how to make the best out of practices
  • Examples of tracing annotations vs metadata
  • Ideas for custom metrics metadata so customers can quickly search info related to metrics
• Share some notes on the Infra being used, env vars, etc.
• Don’t be afraid of using bold, bullet points, etc. strike a balance between being sparse and opinionated
• Add links to the AWS Console when you mention - X-RAY Console - to help customers find that themselves too

Because there are many customers new to Python and developing on AWS Lambda, this is a great opportunity for us to share more general tips as they go along the quickstart too... until we have a public workshop covering these in more depth.

[heitorlessa]

Adding Pablo as a tentative reviewer since he's gone through some hurdles in his first experience that we can improve it.

[mploski]

@heitorlessa Thanks for the feedback! As discussed offline I will change the approach and build the "progressing feeling" where user build final hello-world app from the ground up, adding new functionalities as they go up to the state we have/will have in here https://github.com/aws-samples/cookiecutter-aws-sam-python/blob/master/%7B%7B%20cookiecutter.project_name%20%7D%7D/hello_world/app.py

[mploski]

@heitorlessa @DanyC97 Please re-review if possible :-) Thanks!

[am29d]

This is a really comprehensive quickstart, great work @mploski !

I have added some comments but here are few general points:

• reduce the sentence length and the number of sentences per block. It's hard to keep people's attention so we don't want to lose them.
• Turn into positive. In some parts you present disadvantages and then introduce Powertools as a solution. While it's in general true, it might have some negative tone. Try to convert it to positive expression and show how Powertools can make it easier. You changed your style in the last part of the docs, so it's already there, let's make it consistent.
• "You have a task to do X..." it's a personal taste, but maybe a more guiding style would be approachable with "We want to do X, let's see how it works..."
• Few grammar nitpicks. I am also not a native speaker, so maybe we can run it through some tool and double check.

[heitorlessa]

@mploski All changes are now in this PR, please have a look and feel free to merge if you agree with them.

I largely created sub-sections, made all code snippets consistent, copywriting, suggestions where they can go next at the end of each section, added a Final considerations section, and due to the size renamed from Quickstart to Tutorial ;D

[mploski]

@mploski All changes are now in this PR, please have a look and feel free to merge if you agree with them.

I largely created sub-sections, made all code snippets consistent, copywriting, suggestions where they can go next at the end of each section, added a Final considerations section, and due to the size renamed from Quickstart to Tutorial ;D

It looks really great after all your changes. Thanks a million. Reviewed it, tweaked small things ( typos, making code a bit more consistent + fixing some lines references). I will merge it now :-)