docs: minor improvements (#1021)

saragerion · web-flow · commit 58bfcdf4361a · 2022-07-19T10:02:33.000+02:00
* docs: consistency with blog post messaging, added one-line installation command, reduce font size

* docs: add middy link, add ToC items for CTAs
diff --git a/README.md b/README.md
@@ -1,19 +1,22 @@
 # AWS Lambda Powertools for TypeScript
 
-A suite of TypeScript utilities for AWS Lambda functions to ease adopting best practices such as tracing, structured logging, custom metrics, and more. (AWS Lambda Powertools for [Python](https://github.com/awslabs/aws-lambda-powertools-python) and  AWS Lambda Powertools for [Java](https://github.com/awslabs/aws-lambda-powertools-java) are also available).
+A suite of utilities for AWS Lambda functions to ease the adoption of best practices such as tracing, structured logging, custom metrics, and more.  
+You can use the library in both TypeScript and JavaScript code bases.
+AWS Lambda Powertools for [Python](https://github.com/awslabs/aws-lambda-powertools-python) and  AWS Lambda Powertools for [Java](https://github.com/awslabs/aws-lambda-powertools-java) are also available).
 
-**[📜 Documentation](https://awslabs.github.io/aws-lambda-powertools-typescript/)** | **[NPM](https://www.npmjs.com/org/aws-lambda-powertools)** | **[Roadmap](https://github.com/awslabs/aws-lambda-powertools-roadmap/projects/1)** | **[Examples](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples)**
-
-> **An AWS Developer Acceleration (DevAx) initiative by Specialist Solution Architects | aws-devax-open-source@amazon.com**
+**[📜 Documentation](https://awslabs.github.io/aws-lambda-powertools-typescript/)** | **[NPM](https://www.npmjs.com/org/aws-lambda-powertools)** | **[Roadmap](https://github.com/awslabs/aws-lambda-powertools-roadmap/projects/1)** | **[Examples](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples)** | **[Serverless TypeScript Demo](https://github.com/aws-samples/serverless-typescript-demo)**
 
 ## Table of contents
 
 - [Features](#features)
 - [Getting started](#getting-started)
   - [Installation](#installation)
   - [Examples](#examples)
-- [Credits](#credits)
+  - [Serverless TypeScript Demo](#serverless-typescript-demo-application)
+- [Contribute](#contribute)
+- [Roadmap](#roadmap)
 - [Connect](#connect)
+- [Credits](#credits)
 - [License](#license)
 
 ## Features
@@ -31,6 +34,14 @@ Find the complete project's [documentation here](https://awslabs.github.io/aws-l
 The AWS Lambda Powertools for TypeScript utilities follow a modular approach, similar to the official [AWS SDK v3 for JavaScript](https://github.com/aws/aws-sdk-js-v3).  
 Each TypeScript utility is installed as standalone NPM package.
 
+Install all three core utilities at once with this single command:
+
+```shell
+npm install @aws-lambda-powertools/logger @aws-lambda-powertools/tracer @aws-lambda-powertools/metrics
+```
+
+Or refer to the installation guide of each utility:
+
 👉 [Installation guide for the **Tracer** utility](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/core/tracer#getting-started)
 
 👉 [Installation guide for the **Logger** utility](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/core/logger#getting-started)
@@ -42,15 +53,29 @@ Each TypeScript utility is installed as standalone NPM package.
 * [CDK](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk)
 * [SAM](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/sam)
 
-## Credits
+### Serverless TypeScript Demo application
 
-* Credits for the Lambda Powertools idea go to [DAZN](https://github.com/getndazn) and their [DAZN Lambda Powertools](https://github.com/getndazn/dazn-lambda-powertools/).
+The [Serverless TypeScript Demo](https://github.com/aws-samples/serverless-typescript-demo) shows how to use Lambda Powertools for TypeScript.  
+You can find instructions on how to deploy and load test this application in the [repository](https://github.com/aws-samples/serverless-typescript-demo).
+
+## Contribute
+
+If you are interested in contributing to this project, please refer to our [Contributing Guidelines](https://github.com/awslabs/aws-lambda-powertools-typescript/blob/main/CONTRIBUTING.md).
+
+## Roadmap
+
+The roadmap of Powertools is driven by customers’ demand.  
+Help us prioritize upcoming functionalities or utilities by [upvoting existing RFCs and feature requests](https://github.com/awslabs/aws-lambda-powertools-typescript/issues), or [creating new ones[(https://github.com/awslabs/aws-lambda-powertools-typescript/issues/new/choose), in this GitHub repository.
 
 ## Connect
 
 * **AWS Developers Slack**: `#lambda-powertools` - **[Invite, if you don't have an account](https://join.slack.com/t/awsdevelopers/shared_invite/zt-yryddays-C9fkWrmguDv0h2EEDzCqvw)**
 * **Email**: aws-lambda-powertools-feedback@amazon.com
 
+## Credits
+
+Credits for the Lambda Powertools idea go to [DAZN](https://github.com/getndazn) and their [DAZN Lambda Powertools](https://github.com/getndazn/dazn-lambda-powertools/).
+
 ## License
 
 This library is licensed under the MIT-0 License. See the LICENSE file.
diff --git a/docs/core/logger.md b/docs/core/logger.md
@@ -7,10 +7,11 @@ Logger provides an opinionated logger with output structured as JSON.
 
 ## Key features
 
-* Capture key fields from Lambda context, cold start and structure logging output as JSON
-* Log Lambda event when instructed (disabled by default)
-* Log sampling prints all the logs for a percentage of invocations (disabled by default)
-* Append additional keys to structured log at any point in time
+* Capturing key fields from the Lambda context, cold starts, and structure logging output as JSON.
+* Logging Lambda invocation events when instructed (disabled by default).
+* Printing all the logs only for a percentage of invocations via log sampling (disabled by default).
+* Appending additional keys to structured logs at any point in time.
+* Providing a custom log formatter (Bring Your Own Formatter) to output logs in a structure compatible with your organization’s Logging RFC.
 
 ## Getting started
 
diff --git a/docs/core/metrics.md b/docs/core/metrics.md
@@ -9,10 +9,10 @@ These metrics can be visualized through [Amazon CloudWatch Console](https://cons
 
 ## Key features
 
-* Aggregate up to 100 metrics using a single CloudWatch EMF object (large JSON blob)
-* Validate against common metric definitions mistakes (metric unit, values, max dimensions, max metrics, etc)
-* Metrics are created asynchronously by CloudWatch service, no custom stacks needed
-* Context manager to create a one off metric with a different dimension
+* Aggregating up to 100 metrics using a single CloudWatch EMF object (large JSON blob).
+* Validating your metrics against common metric definitions mistakes (for example, metric unit, values, max dimensions, max metrics).
+* Metrics are created asynchronously by the CloudWatch service. You do not need any custom stacks, and there is no impact to Lambda function latency.
+* Creating a one-off metric with different dimensions.
 
 ## Terminologies
 
diff --git a/docs/core/tracer.md b/docs/core/tracer.md
@@ -7,11 +7,11 @@ Tracer is an opinionated thin wrapper for [AWS X-Ray SDK for Node.js](https://gi
 
 ## Key features
 
-* Auto capture cold start and service name as annotations, and responses or full exceptions as metadata
-* Auto-disable when not running in AWS Lambda environment
-* Automatically trace HTTP(s) clients and generate segments for each request
-* Support tracing functions via decorators, middleware, and manual instrumentation
-* Support tracing AWS SDK v2 and v3 via AWS X-Ray SDK for Node.js  
+* Auto-capturing cold start and service name as annotations, and responses or full exceptions as metadata.
+* Automatically tracing HTTP(S) clients and generating segments for each request.
+* Supporting tracing functions via decorators, middleware, and manual instrumentation.
+* Supporting tracing AWS SDK v2 and v3 via AWS X-Ray SDK for Node.js.
+* Auto-disable tracing when not running in the Lambda environment.
 
 ![Tracer showcase](../media/tracer_utility_showcase.png)
 
diff --git a/docs/index.md b/docs/index.md
@@ -3,7 +3,8 @@ title: Homepage
 description: AWS Lambda Powertools for TypeScript
 ---
 
-AWS Lambda Powertools for TypeScript provides a suite of utilities for AWS Lambda functions running on the Node.js runtime, to ease the adoption of best practices such as tracing, structured logging, custom metrics, and more.
+AWS Lambda Powertools for TypeScript provides a suite of utilities for AWS Lambda functions running on the Node.js runtime, to ease the adoption of best practices such as tracing, structured logging, custom metrics, and more.  
+You can use the library in both TypeScript and JavaScript code bases.
 
 ## Tenets
 
@@ -20,7 +21,7 @@ Core utilities such as Tracer, Logger, Metrics, and Event Handler will be availa
 
 | Utility | Description
 | ------------------------------------------------- | ---------------------------------------------------------------------------------
-[Tracer](./core/tracer.md) | Utilities to trace Lambda function handlers, and both synchronous and asynchronous functions
+[Tracer](./core/tracer.md) | Trace Lambda function handlers, and both synchronous and asynchronous functions
 [Logger](./core/logger.md) | Structured logging made easier, and a middleware to enrich log items with key details of the Lambda context
 [Metrics](./core/metrics.md) | Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF)
 
@@ -29,12 +30,28 @@ Core utilities such as Tracer, Logger, Metrics, and Event Handler will be availa
 The AWS Lambda Powertools for TypeScript utilities (which from here will be referred as Powertools) follow a modular approach, similar to the official [AWS SDK v3 for JavaScript](https://github.com/aws/aws-sdk-js-v3).
 Each TypeScript utility is installed as standalone NPM package.
 
+Install all three core utilities at once with this single command:
+
+```shell
+npm install @aws-lambda-powertools/logger @aws-lambda-powertools/tracer @aws-lambda-powertools/metrics
+```
+
+Or refer to the installation guide of each utility: 
+
 [Installation guide for the **Tracer** utility](./core/tracer.md#getting-started)
 
 [Installation guide for the **Logger** utility](./core/logger.md#getting-started)
 
 [Installation guide for the **Metrics** utility](./core/metrics.md#getting-started)
 
+## Instrumentation
+
+You can instrument your code with Powertools in three different ways:  
+
+* **Middy** middleware. It is the best choice if your existing code base relies on the [Middy](https://middy.js.org/docs/) middleware engine. Powertools offers compatible Middy middleware to make this integration seamless.
+* **Method decorator**. Use [TypeScript method decorators](https://www.typescriptlang.org/docs/handbook/decorators.html#method-decorators) if you prefer writing your business logic using TypeScript Classes. If you aren’t using Classes, this requires the most significant refactoring.
+* **Manually**. It provides the most granular control. It’s the most verbose approach, with the added benefit of no additional dependency and no refactoring to [TypeScript Classes](https://www.typescriptlang.org/docs/handbook/classes.html).
+
 ## Environment variables
 
 !!! info
@@ -50,14 +67,18 @@ Each TypeScript utility is installed as standalone NPM package.
 | **POWERTOOLS_TRACER_CAPTURE_HTTPS_REQUESTS** | Captures HTTP(s) requests as segments.                                                 | [Tracer](./core/tracer)   | `true`                |
 | **POWERTOOLS_LOGGER_LOG_EVENT**              | Logs incoming event                                                                    | [Logger](./core/logger)   | `false`               |
 | **POWERTOOLS_LOGGER_SAMPLE_RATE**            | Debug log sampling                                                                     | [Logger](./core/logger)   | `0`                   |
-| **POWERTOOLS_LOGGER_LOG_EVENT**              | Logs incoming events                                                                   | [Logger](./core/logger)   | `false`               |
 | **LOG_LEVEL**                                | Sets logging level                                                                     | [Logger](./core/logger)   | `INFO`                |
 
 ## Examples
 
 * [CDK](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk){target="_blank"}
 * [SAM](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/sam){target="_blank"}
 
+## Serverless TypeScript demo application
+
+The [Serverless TypeScript Demo](https://github.com/aws-samples/serverless-typescript-demo) shows how to use Lambda Powertools for TypeScript.  
+You can find instructions on how to deploy and load test this application in the [repository](https://github.com/aws-samples/serverless-typescript-demo).
+
 ## Credits
 
 * Credits for the Lambda Powertools idea go to [DAZN](https://github.com/getndazn){target="_blank"} and their [DAZN Lambda Powertools](https://github.com/getndazn/dazn-lambda-powertools/){target="_blank"}.
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
@@ -1,19 +1,15 @@
-.md-grid {
-    max-width: 81vw;
+@font-face {
+    font-size: 0.65rem;
 }
 
-.md-typeset table:not([class]) {
-    font-size: 0.75rem;
+.md-grid {
+    max-width: 81vw;
 }
 
 .md-typeset a {
     border-bottom: 0.1px dashed black;
 }
 
-.md-typeset table:not([class]) {
-    font-size: 0.75rem;
-}
-
 .md-nav__link--active {
     font-weight: bold;
 }
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -34,10 +34,12 @@ theme:
     - navigation.sections
     - navigation.expand
     - navigation.top
+    - toc.follow
     - navigation.instant
     - navigation.indexes
     - navigation.tracking
     - content.code.annotate
+    - toc.integrate
   icon:
     repo: fontawesome/brands/github
   logo: media/aws-logo-light.svg
diff --git a/packages/logger/README.md b/packages/logger/README.md
@@ -1,18 +1,30 @@
 # AWS Lambda Powertools for TypeScript
 
-A suite of TypeScript utilities for AWS Lambda functions to ease adopting best practices such as tracing, structured logging, custom metrics, and more. (AWS Lambda Powertools for [Python](https://github.com/awslabs/aws-lambda-powertools-python) and AWS Lambda Powertools for [Java](https://github.com/awslabs/aws-lambda-powertools-java) are also available).
+A suite of utilities for AWS Lambda functions to ease the adoption of best practices such as tracing, structured logging, custom metrics, and more.  
+You can use the library in both TypeScript and JavaScript code bases.
+AWS Lambda Powertools for [Python](https://github.com/awslabs/aws-lambda-powertools-python) and  AWS Lambda Powertools for [Java](https://github.com/awslabs/aws-lambda-powertools-java) are also available).
 
-**[📜 Documentation](https://awslabs.github.io/aws-lambda-powertools-typescript/)** | **[NPM](https://www.npmjs.com/org/aws-lambda-powertools)** | **[Roadmap](https://github.com/awslabs/aws-lambda-powertools-roadmap/projects/1)** | **[Examples](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples)**
+**[📜 Documentation](https://awslabs.github.io/aws-lambda-powertools-typescript/)** | **[NPM](https://www.npmjs.com/org/aws-lambda-powertools)** | **[Roadmap](https://github.com/awslabs/aws-lambda-powertools-roadmap/projects/1)** | **[Examples](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples)** | **[Serverless TypeScript Demo](https://github.com/aws-samples/serverless-typescript-demo)**
 
-> **An AWS Developer Acceleration (DevAx) initiative by Specialist Solution Architects | aws-devax-open-source@amazon.com**
+## Table of contents
+
+- [Features](#features)
+- [Getting started](#getting-started)
+  - [Installation](#installation)
+  - [Examples](#examples)
+  - [Serverless TypeScript Demo](#serverless-typescript-demo-application)
+- [Contribute](#contribute)
+- [Roadmap](#roadmap)
+- [Connect](#connect)
+- [Credits](#credits)
+- [License](#license)
 
 ## Features
 
 * **[Tracer](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/core/tracer/)** - Utilities to trace Lambda function handlers, and both synchronous and asynchronous functions
 * **[Logger](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/core/logger/)** - Structured logging made easier, and a middleware to enrich log items with key details of the Lambda context
 * **[Metrics](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/core/metrics/)** - Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF)
 
-
 ## Getting started
 
 Find the complete project's [documentation here](https://awslabs.github.io/aws-lambda-powertools-typescript).
@@ -22,6 +34,14 @@ Find the complete project's [documentation here](https://awslabs.github.io/aws-l
 The AWS Lambda Powertools for TypeScript utilities follow a modular approach, similar to the official [AWS SDK v3 for JavaScript](https://github.com/aws/aws-sdk-js-v3).  
 Each TypeScript utility is installed as standalone NPM package.
 
+Install all three core utilities at once with this single command:
+
+```shell
+npm install @aws-lambda-powertools/logger @aws-lambda-powertools/tracer @aws-lambda-powertools/metrics
+```
+
+Or refer to the installation guide of each utility:
+
 👉 [Installation guide for the **Tracer** utility](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/core/tracer#getting-started)
 
 👉 [Installation guide for the **Logger** utility](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/core/logger#getting-started)
@@ -33,15 +53,29 @@ Each TypeScript utility is installed as standalone NPM package.
 * [CDK](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/cdk)
 * [SAM](https://github.com/awslabs/aws-lambda-powertools-typescript/tree/main/examples/sam)
 
-## Credits
+### Serverless TypeScript Demo application
+
+The [Serverless TypeScript Demo](https://github.com/aws-samples/serverless-typescript-demo) shows how to use Lambda Powertools for TypeScript.  
+You can find instructions on how to deploy and load test this application in the [repository](https://github.com/aws-samples/serverless-typescript-demo).
 
-* Credits for the Lambda Powertools idea go to [DAZN](https://github.com/getndazn) and their [DAZN Lambda Powertools](https://github.com/getndazn/dazn-lambda-powertools/).
+## Contribute
+
+If you are interested in contributing to this project, please refer to our [Contributing Guidelines](https://github.com/awslabs/aws-lambda-powertools-typescript/blob/main/CONTRIBUTING.md).
+
+## Roadmap
+
+The roadmap of Powertools is driven by customers’ demand.  
+Help us prioritize upcoming functionalities or utilities by [upvoting existing RFCs and feature requests](https://github.com/awslabs/aws-lambda-powertools-typescript/issues), or [creating new ones[(https://github.com/awslabs/aws-lambda-powertools-typescript/issues/new/choose), in this GitHub repository.
 
 ## Connect
 
-* **AWS Developers Slack**: `#lambda-powertools`- **[Invite, if you don't have an account](https://join.slack.com/t/awsdevelopers/shared_invite/zt-yryddays-C9fkWrmguDv0h2EEDzCqvw)**
+* **AWS Developers Slack**: `#lambda-powertools` - **[Invite, if you don't have an account](https://join.slack.com/t/awsdevelopers/shared_invite/zt-yryddays-C9fkWrmguDv0h2EEDzCqvw)**
 * **Email**: aws-lambda-powertools-feedback@amazon.com
 
+## Credits
+
+Credits for the Lambda Powertools idea go to [DAZN](https://github.com/getndazn) and their [DAZN Lambda Powertools](https://github.com/getndazn/dazn-lambda-powertools/).
+
 ## License
 
-This library is licensed under the MIT-0 License. See the LICENSE file.
+This library is licensed under the MIT-0 License. See the LICENSE file.
diff --git a/packages/metrics/README.md b/packages/metrics/README.md
diff --git a/packages/tracer/README.md b/packages/tracer/README.md

Original file line number	Diff line number	Diff line change
`@@ -1,19 +1,15 @@`
`1`		`-.md-grid {`
`2`		`- max-width: 81vw;`
	`1`	`+@font-face {`
	`2`	`+ font-size: 0.65rem;`
`3`	`3`	`}`
`4`	`4`
`5`		`-.md-typeset table:not([class]) {`
`6`		`- font-size: 0.75rem;`
	`5`	`+.md-grid {`
	`6`	`+ max-width: 81vw;`
`7`	`7`	`}`
`8`	`8`
`9`	`9`	`.md-typeset a {`
`10`	`10`	`border-bottom: 0.1px dashed black;`
`11`	`11`	`}`
`12`	`12`
`13`		`-.md-typeset table:not([class]) {`
`14`		`- font-size: 0.75rem;`
`15`		`-}`
`16`		`-`
`17`	`13`	`.md-nav__link--active {`
`18`	`14`	`font-weight: bold;`
`19`	`15`	`}`