Expand example documentation (#2570)

## Motivation and Context

The current README for the example services is fairly spartan.

## Description

I've expanded the README, specifically:

- Clean up some markup
- Document pre-reqs.
- Document all make targets.
- Avoid the $BINARY because it looks like a bash variable.
- Expand intro

## Testing
<!--- Please describe in detail how you tested your changes -->
<!--- Include details of your testing environment, and the tests you ran
to -->
<!--- see how your change affects other areas of the code, etc. -->

n/a

## Checklist

n/a

----

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

---------

Co-authored-by: Matteo Bigoi <1781140+crisidev@users.noreply.github.com>
Co-authored-by: david-perez <d@vidp.dev>

Author: 3 people

examples/README.md

@@ -1,49 +1,88 @@
 # Smithy Rust Server SDK examples
 
-This folder contains an example services showcasing the service framework capabilities and to run benchmarks.
+This folder contains some example services showcasing Smithy Rust Server SDK, 
+also known as the Rust service framework, capabilities and to run benchmarks.
 
-- `/pokemon-service`, a HTTP server implementation demonstrating [middleware](https://awslabs.github.io/smithy-rs/design/server/middleware.html)
-and [extractors](https://awslabs.github.io/smithy-rs/design/server/from_parts.html).
-- `/pokemon-service-tls`, a minimal HTTPS server implementation.
-- `/pokemon-service-lambda`, a minimal Lambda deployment.
+Three server implementations are available:
 
-The `/{binary}/tests` folders are integration tests involving the generated clients.
+- `/pokemon-service`, a HTTP server demonstrating [middleware] and [extractors].
+- `/pokemon-service-tls`, a HTTPS server. This server can do 
+   its own TLS negotiation, rather than relying on a load balancer. 
+- `/pokemon-service-lambda`, a server that can be deployed onto AWS Lambda.
 
-## Build
+These servers, and their clients, are generated using smithy-rs. You're invited
+to benchmark the performance of these servers to see whether smithy-rs might be
+a suitable choice for implementing your web service.
 
-Since this example requires both the server and client SDK to be code-generated
+[middleware]: https://awslabs.github.io/smithy-rs/design/server/middleware.html
+[extractors]: https://awslabs.github.io/smithy-rs/design/server/from_parts.html
+
+
+## Pre-requisites
+
+You will need install Java 11 to run the smithy-rs code generator and an
+installation of Rust, including `cargo`, to compile the generated code.
+
+(Optional) The [Cargo Lambda](https://cargo-lambda.info/) sub-command for 
+`cargo` is required to support the AWS Lambda integration.
+
+
+## Building
+
+Since these examples require both the server and client SDK to be code-generated
 from their [model](/codegen-server-test/model/pokemon.smithy), a Makefile is
 provided to build and run the service. Just run `make` to prepare the first
 build.
 
 Once the example has been built successfully the first time, idiomatic `cargo`
 can be used directly.
 
-`make distclean` can be used for a complete cleanup of all artefacts.
+### Make targets:
+
+- `codegen`: generates the Pokémon service crates (default)
+- `build`: compiles the generated client and server
+- `clean`: deletes build artifacts
+- `clippy`: lints the code
+- `distclean`: delete generated code and build artifacts 
+- `doc-open`: builds and opens the rustdoc documentation
+- `lambda_invoke`: invokes a running server 
+- `lambda_watch`: runs the service on an emulated AWS Lambda environment
+- `run`: runs the Pokémon service
+- `test`: runs integration and unit tests
+
 
-## Run
+## Running services
 
-To run a binary use
+To run one of the three server implementations locally, provide the appropriate 
+service name to the `--bin` flag:
 
 ```bash
-cargo run -p $BINARY
+cargo run --bin pokemon-service[(-lambda|-tls)]
 ```
 
-CLI arguments can be passed to the servers, use
+CLI arguments can be passed to the server binaries by adding them after `--`. 
+For example, to see a service's help information, use the following:
 
 ```bash
-cargo run -p $BINARY -- --help
+cargo run --bin <service> -- --help
 ```
 
-for more information.
+## Testing
 
-## Test
+The `/pokemon-test*/tests` folders provide integration tests involving the 
+generated clients.
 
-`cargo test` can be used to spawn a service and run some simple integration
-tests against it. Use `-p $BINARY` to filter by package.
+They can be invoked with `cargo test`. This will spawn each service in turn 
+and run some integration tests against it. Use `-p <package>` to filter by 
+package.
 
 More info can be found in the `tests` folder of each package.
 
-## Benchmarks
 
-Please see [BENCHMARKS.md](/examples/BENCHMARKS.md).
+## Benchmarking
+
+Servers running locally (see "Running services") can be benchmarked with any 
+load testing tool, such as Artillery or `wrk`.
+
+Please see [BENCHMARKS.md](/examples/BENCHMARKS.md) for benchmarking results 
+produced by the smithy-rs team.