Update README.md (#591)

README.md

@@ -1,4 +1,5 @@
-# <img alt="Smithy" src="https://github.com/smithy-lang/smithy/blob/main/docs/_static/smithy-anvil.svg?raw=true" width="32"> Smithy Java 
+# <img alt="Smithy" src="https://github.com/smithy-lang/smithy/blob/main/docs/_static/smithy-anvil.svg?raw=true" width="32"> Smithy Java
+
 [![ci](https://github.com/smithy-lang/smithy-java/actions/workflows/ci.yml/badge.svg)](https://github.com/smithy-lang/smithy-java/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 
@@ -8,6 +9,7 @@
 > This project is still in development and is not intended for use in production.
 
 ---
+
 This repository contains two major components:
 1. Smithy code generators for Java
 2. Core modules and interfaces for building services and clients in Java
@@ -19,11 +21,12 @@ The [codegen](./codegen) directory contains the source code for generating clien
 > This repository does not contain any generated clients, such as for S3 or other AWS services. 
 > Rather, these are the tools that facilitate the generation of those clients and non-AWS Smithy clients.
 
-## Getting Started 
+## Getting Started
+
 If this is your first time using Smithy, follow the [Smithy Quickstart guide](https://smithy.io/2.0/quickstart.html) 
 to learn the basics and create a simple Smithy model.
 
-For a guided tour of this project, see the [Smithy Java Quickstart guide](https://smithy.io/2.0/java/quickstart.html).
+For a guided introduction to this project, see the [Smithy Java Quickstart guide](https://smithy.io/2.0/java/quickstart.html).
 
 The [examples](./examples) are standalone projects that showcase the usage of Smithy Java for generating clients 
 and building services. These examples can be used as a template for a new project using the 
@@ -35,6 +38,7 @@ and building services. These examples can be used as a template for a new projec
 > Smithy-Java only supports **Java 17** or later. Older Java versions are not supported.
 
 ### Codegen (Gradle)
+
 To use the Smithy Java code generators with Gradle, first create a Smithy Gradle project. 
 
 > [!NOTE]
@@ -97,75 +101,94 @@ tasks.named("compileJava") {
 ```
 
 ### Stability
+
 Classes and API's annotated with `@SmithyInternal` are for internal use by Smithy-Java libraries and should **not** be
 used by Smithy users. API's annotated with `@SmithyUnstableApi` are subject to change in future releases.
 
 ## Core modules and Interfaces
+
 ### Common
+
 - `core` - Provides basic functionality for (de)serializing generated types and defining `Schema`'s, minimal representations
            of the Smithy data model for use at runtime.
 - `io` - Common I/O functionality for clients/servers.
 - `auth-api` - shared Authorization/Authentication API for clients and servers.
 - `framework-errors` - Common errors that could be thrown by the Smithy Java framework.
 
 ### Client
+
 - `client-core` - Provides protocol and transport agnostic functionality for clients. 
                   All generated clients require this package as a runtime dependency.
 - `client-http` - Client-side implementation of HTTP transport.
 - `dynamic-client` - Smithy client that exposes a dynamic API that doesn't require codegen.
 
 ### Server
+
 - `server-core` - Provides protocol and transport agnostic functionality for servers. 
                   All generated server-stubs require this package as a runtime dependency.
 - `server-netty` - Provides an HTTP server implementation using the [Netty](https://netty.io/) runtime.
 
-### Codegen 
+### Codegen
+
 - `codegen:core` - Provides the basic framework necessary for codegen plugins and integrations to generate Java 
                    code from a Smithy model. Only codegen plugins and integrations should depend on this directly.
 - `codegen:plugins` - Aggregate package that provides all code generation plugins.
 
 Codegen integrations that modify the code generated by codegen plugins can be found in [codegen/integrations](codegen/integrations).
 
 ### Protocols
-Smithy Java, like the Smithy IDL, is protocol-agnostic. Servers to support any number of protocols and clients can 
+
+Smithy Java, like the Smithy IDL, is protocol-agnostic. Servers support any number of protocols and clients can 
 set the protocol to use at runtime.
 
+> [!NOTE]
+> The `rpcv2-cbor`protocol is a generic binary protocol provided by Smithy Java that can be a good
+> choice for services that want a fast, compact data format.
+
 The [`protocol-test-harness`](protocol-test-harness) package provides a framework for testing protocols.
 
-#### Client 
+#### Client
+
 - `client-rpcv2-cbor` - Implementation [rpcv2-cbor](https://smithy.io/2.0/additional-specs/protocols/smithy-rpc-v2.html#smithy-rpc-v2-cbor-protocol) protocol.
 - `aws-client-awsjson` - Implementation of [AWS JSON 1.0](https://smithy.io/2.0/aws/protocols/aws-json-1_0-protocol.html#aws-json-1-0-protocol) and [AWS JSON 1.1](https://smithy.io/2.0/aws/protocols/aws-json-1_1-protocol.html#aws-json-1-1-protocol) protocols.
 - `aws-client-restjson` - Implementation of [AWS restJson1](https://smithy.io/2.0/aws/protocols/aws-json-1_1-protocol.html#aws-json-1-1-protocol) protocol.
-- `aws-client-restXml` - Implementation of  [AWS restXml](https://smithy.io/2.0/aws/protocols/aws-restxml-protocol.html#aws-restxml-protocol) protocol.
+- `aws-client-restXml` - Implementation of [AWS restXml](https://smithy.io/2.0/aws/protocols/aws-restxml-protocol.html#aws-restxml-protocol) protocol.
 
 #### Server
+
 - `server-rpcv2-cbor` - Implementation [rpcv2-cbor](https://smithy.io/2.0/additional-specs/protocols/smithy-rpc-v2.html#smithy-rpc-v2-cbor-protocol) protocol.
 - `aws-server-restjson` - Implementation of [AWS restJson1](https://smithy.io/2.0/aws/protocols/aws-json-1_1-protocol.html#aws-json-1-1-protocol) protocol.
 
 #### Codecs
+
 Codecs provide basic (de)serialization functionality for protocols.
 - `json-codec` - (de)serialization functionality for [JSON](https://www.json.org/json-en.html) format
 - `cbor-codec` - Binary (de)serialization functionality for [CBOR](https://cbor.io/) format 
 - `xml-codec` - (de)serialization functionality for [XML](https://www.w3.org/TR/REC-xml/) format
 
 ### Utilities 
+
 - `jmespath` - [JMESPath](https://jmespath.org/) implementation that allows querying a `Document` using a JMESPath expression.
 
 
 ## Development
+
 See [CONTRIBUTING](CONTRIBUTING.md) for more information on contributing to the Smithy-Java project.
 
 ### Pre-push hooks
+
 Pre-push hooks are automatically added for unix users via the `addGitHooks` gradle task.
 
-**Note**: In order to successfully execute the pre-defined hooks you must have the `smithy` CLI installed. 
+**Note**: In order to successfully execute the pre-defined git hooks you must have the `smithy` CLI installed. 
 See [installation instructions](https://smithy.io/2.0/guides/smithy-cli/cli_installation.html) if you do not already have the CLI installed.
 
 ## Security
+
 If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our 
 [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). 
 Please do **not** create a public GitHub issue.
 
 ## License
+
 This project is licensed under the Apache-2.0 License.