Fix the visual noise

README.md

@@ -6,14 +6,17 @@
 ## Current Project Status
 ![Current Version](https://img.shields.io/github/v/tag/open-telemetry/opentelemetry-php)
 
-This project currently lives in a pre-alpha status.  Our current release is not production ready; it has been created in order to receive feedback from the community.
+This project currently lives in a pre-alpha status.  Our current release is not production ready. It has been created in order to receive feedback from the community.
 
-There is a supplemental repository for OpenTelemetry PHP contributions that are not part of the core distribution of the library. Typically, these contributions are vendor specific receivers/exporters and/or components that are only useful to a relatively small number of users.  This repository can be found here:
-https://github.com/open-telemetry/opentelemetry-php-contrib/
+There is a supplemental repository for OpenTelemetry PHP contributions that are not part of the core 
+distribution of the library. Typically, these contributions are vendor specific receivers/exporters and/or 
+components that are only useful to a relatively small number of users.  This repository can be found
+[here.](https://github.com/open-telemetry/opentelemetry-php-contrib/)
 
-We attempt to keep the [OpenTelemetry Specification Matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/master/spec-compliance-matrix.md) up to date in order to show which features are available and which have not yet been implemented.
-
-If you find an inconsistency in the data in the matrix vs. the data in this repository, please let us know in our Slack channel, and we'll get it rectified.
+We attempt to keep the [OpenTelemetry Specification Matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/master/spec-compliance-matrix.md) 
+up to date to track the available features and the ones we are yet to implement. If you 
+find an inconsistency between the data in the matrix and this repository, please let us know on our [Slack channel](https://cloud-native.slack.com/archives/C01NFPCV44V) 
+and we'll look into it!
 
 ## Communication
 Most of our communication is done on CNCF Slack in the channel [otel-php](https://cloud-native.slack.com/archives/C01NFPCV44V).
@@ -22,7 +25,7 @@ To sign up, create a CNCF Slack account [here](http://slack.cncf.io/)
 Our meetings are held weekly on zoom on Wednesdays at 10:30am PST / 1:30pm EST.  
 A Google calendar invite with the included zoom link can be found [here](https://calendar.google.com/event?action=TEMPLATE&tmeid=N2VtZXZmYnVmbzZkYjZkbTYxdjZvYTdxN21fMjAyMDA5MTZUMTczMDAwWiBrYXJlbnlyeHVAbQ&tmsrc=google.com_b79e3e90j7bbsa2n2p5an5lf60%40group.calendar.google.com&scp=ALL)
 
-Our open issues can all be found in the [github issues tab](https://github.com/open-telemetry/opentelemetry-php/issues).  Feel free to reach out on Slack if you have any additional questions about these issues; we are always happy to talk through implementation details.
+Our open issues can all be found in the [GitHub issues tab](https://github.com/open-telemetry/opentelemetry-php/issues).  Feel free to reach out on Slack if you have any additional questions about these issues; we are always happy to talk through implementation details.
 
 ## Requirements
 The library currently requires a PHP version of 7.4.x or 8.0.x (PHP 8.1 compatibility is in the works)
@@ -32,7 +35,7 @@ The library currently requires a PHP version of 7.4.x or 8.0.x (PHP 8.1 compatib
 ---
 
 #### REQUIRED DEPENDENCIES
-#### 1.) Install PSR17/18 implementations
+####1) Install PSR17/18 implementations
 
 The library has a dependency on both a [HTTP Factories (PSR17)](https://www.php-fig.org/psr/psr-17/)
 and a [php-http/async-client](https://docs.php-http.org/en/latest/clients.html) implementation.
@@ -48,7 +51,7 @@ and [this link](https://packagist.org/providers/php-http/async-client-implementa
 
 **The PHP gRPC extension is only needed, if you want to use the OTLP GRPC Exporter.**
 
-The three ways to install the gRPC extension are described below. Keep in mind, that whatever way
+Three ways to install the gRPC extension are described below. Keep in mind, that whatever way
 to install the extension you choose, the compilation can take up to 10-15 minutes. (As an alternative you can search for
 a pre-compiled extension binary for your OS and PHP version, or you might be lucky and the package manager of your OS
 provides a package for the extension)
@@ -66,31 +69,31 @@ provides a package for the extension)
 - **Manually compiling the extension**, which is not really complicated either, but you should know
   what you are doing, so we won't cover it here.
 
-> Notice: The artifact of the gRPC extension can be as large as 100mb (!!!), there are 'hacks' to reduce that size,
-> which you can find [in this thread](https://github.com/grpc/grpc/issues/23626). Use at your own risk.
+> Notice: The artifact of the gRPC extension can be as large as 100mb (!!!), Some 'hacks' to reduce that size,
+>are mentioned [in this thread](https://github.com/grpc/grpc/issues/23626). **Use at your own risk.**
 
-#### 2.) Install PHP [ext-mbstring](https://www.php.net/manual/en/book.mbstring.php)
+#### 2) Install PHP [ext-mbstring](https://www.php.net/manual/en/book.mbstring.php)
 
 The library will load the `symfony/polyfill-mbstring` package, but for better performance you should install
 the  PHP mbstring extension. You can use the same install methods as described for the gRPC extension above,
 however most OS` package managers provide a package for the extension.
 
-#### 3.) Install PHP [ext-zlib](https://www.php.net/manual/en/book.zlib.php)
+#### 3) Install PHP [ext-zlib](https://www.php.net/manual/en/book.zlib.php)
 
 In order to use compression in HTTP requests you should install
 the  PHP zlib extension. You can use the same install methods as described for the gRPC extension above,
 however most OS` package managers provide a package for the extension.
 
-#### 4.) Install PHP [ext-ffi](https://www.php.net/manual/en/book.ffi.php)
+#### 4) Install PHP [ext-ffi](https://www.php.net/manual/en/book.ffi.php)
 
 _Experimental_ support for using fibers in PHP 8.1 for Context storage requires the `ffi` extension, and can
 be enabled by setting the `OTEL_PHP_FIBERS_ENABLED` environment variable to a truthy value (`1`, `true`, `on`).
 
 Using fibers with non-`CLI` SAPIs may require preloading of bindings. One way to achieve this is setting [`ffi.preload`](https://www.php.net/manual/en/ffi.configuration.php#ini.ffi.preload) to `src/Context/fiber/zend_observer_fiber.h` and setting [`opcache.preload`](https://www.php.net/manual/en/opcache.preloading.php) to `vendor/autoload.php`.
 
-#### 5.) Install PHP [ext-protobuf](https://pecl.php.net/package/protobuf)
+#### 5) Install PHP [ext-protobuf](https://pecl.php.net/package/protobuf)
 
-** The PHP protobuf extension is optional when using either the `OTLPHttp` or `OTLPGrpc` exporters.**
+**The PHP protobuf extension is optional when using either the `OTLPHttp` or `OTLPGrpc` exporters.**
 
 The protobuf extension makes both exporters more performant. _Note: there are some deprecation warnings with protobuf and PHP 8.1_
 
@@ -118,17 +121,21 @@ $ composer require open-telemetry/opentelemetry
 ## Development
 For repeatability and consistency across different operating systems, we use the [3 Musketeers pattern](https://3musketeers.io/). If you're on Windows, it might be a good idea to use Git bash for following the steps below.
 
+**Note: After cloning the repository, copy `.env.dist` to `.env`.** 
+
+Skipping the step above would result in a "`The "PHP_USER" variable is not set. Defaulting to a blank string`" warning
+
 We use `docker` and `docker-compose` to perform a lot of our static analysis and testing. If you're planning to develop for this library, it'll help to install `docker engine` and `docker-compose`.
 
-You can find installation instructions for these packages can be found [here](https://docs.docker.com/install/), under the `Docker Engine` and `Docker Compose` submenus respectively.
+The installation instructions for these tools are [here](https://docs.docker.com/install/), under the `Docker Engine` and `Docker Compose` submenus respectively.
 
 To ensure you have all the correct packages installed locally in your dev environment, you can run
 
 ```bash
 make install
 ```
 
-This will install all the necessary vendored libraries that the project uses to
+This will install all the library dependencies to
 the `/vendor` directory.
 
 To update these dependencies, you can run
@@ -137,22 +144,20 @@ To update these dependencies, you can run
 make update
 ```
 
-In order to update all the vendored libraries in the `/vendor` directory.
 
 
 ## Pull Requests
 
-Once you've made the update to the codebase that you'd like to submit, you may [create a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) to the opentelemetry-php project.
+To propose changes to the codebase, you need to [open a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) to the opentelemetry-php project.
 
-After you open the pull request, the CI/CD pipeline will run all the associated [github actions](https://github.com/open-telemetry/opentelemetry-php/actions/workflows/php.yml).
+After you open the pull request, the CI will run all the associated [github actions](https://github.com/open-telemetry/opentelemetry-php/actions/workflows/php.yml).
 
-You can simulate the important GitHub actions locally before you submit your PR by running the following command:
+To ensure your PR doesn't emit a failure with GitHub actions, it's recommended that you run important the CI
+tests locally with the following command:
 
 ```bash
 make all
 ```
-Note: Copying `.env.dist` to `.env` fixes the warning ```The "PHP_USER" variable is not set. Defaulting to a blank string.```
-
 This does the following things:
 
 * Installs/updates all the required dependencies for the project
@@ -176,7 +181,7 @@ Our protobuf files are committed to the repository into the `/proto` folder.  Th
 upstream.  These get updated when the [opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto)
 repo has a meaningful update.  The maintainer SIG is discussing a way to make this more automatic in the future.
 
-If you'd like to generate protobuf files for use with this repository, one can run the following command:
+To generate protobuf files for use with this repository, you can run the following command:
 
 ```bash
 make protobuf
@@ -188,7 +193,7 @@ repository.
 
 
 ## Semantic Conventions Generation
-A generated semantic convention files are committed to the repository in the `/src/SemConv` directory. These files
+Autogenerated semantic convention files are committed to the repository in the `/src/SemConv` directory. These files
 get updated when new version of [opentelemetry-specification](https://github.com/open-telemetry/opentelemetry-specification)
 released.
 
@@ -201,13 +206,12 @@ Run this command in the root of this repository.
 ## Styling
 We use [PHP-CS-Fixer](https://github.com/FriendsOfPHP/PHP-CS-Fixer) for our code linting and standards fixer.  The associated configuration for this standards fixer can be found in the root of the repository [here](https://github.com/open-telemetry/opentelemetry-php/blob/master/.php_cs)
 
-To ensure that your code is stylish, you can run the following command:
+To ensure that your code follows our coding standards, you can run:
 ```bash
 make style
 ```
-
-This process will print out the fixes that it is making to your
-associated files.  Usually this process is performed as part of a code checkin.  This process runs during CI and is a required check.  Code that doesn't follow this style pattern will emit a failure in CI.
+This command executes a required test that also runs during CI. This process performs the required fixes and prints them out.
+Code that doesn't meet the style pattern will emit a failure with GitHub actions.
 
 ## Static Analysis
 We use [Phan](https://github.com/phan/phan/) for static analysis.  Currently, our phan configuration is just a standard default analysis configuration.  You can use our phan docker wrapper to easily perform static analysis on your changes.
@@ -263,13 +267,10 @@ You can use the [examples/AlwaysOnZipkinExample.php](/examples/AlwaysOnZipkinExa
 
 You can also use the [examples/AlwaysOnJaegerExample.php](/examples/AlwaysOnJaegerExample.php) file to test out the reference implementation we have for Jaeger.  This example performs a sample trace with a grouping of 5 spans and POSTs the result to a local Jaeger instance.
 
-You can use the [examples/AlwaysOnZipkinToNewrelicExample.php](/examples/AlwaysOnZipkinToNewrelicExample.php) file to test out the reference implementation we have for zipkin to Newrelic.  This example performs a sample trace with spans and POSTs the result to a Newrelic endpoint.  This requires a license key (free accounts available) to be set in the environment (NEW_RELIC_INSERT_KEY) to authenticate to the backend.
-
-You can use the [examples/AlwaysOnNewrelicExample.php](/examples/AlwaysOnNewrelicExample.php) file to test out the reference implementation we have for Newrelic.  This example performs a sample trace with spans and POSTs the result to a Newrelic endpoint.  This requires a license key (free accounts available) set in the environment (NEW_RELIC_INSERT_KEY) to authenticate to the backend.
 
-The PHP for all examples should execute by itself (if you have a zipkin or jaegar instance running on localhost), but if you'd like a no-fuss way to test this out with docker and docker-compose, you can perform the following simple steps:
+If you'd like a no-fuss way to test this out with docker and docker-compose, you can perform the following simple steps:
 
-1)  Install the necessary dependencies by running `make install`.  This will install the composer dependencies and store them in `/vendor`
+1)  Install the necessary dependencies by running `make install`. 
 2)  Execute the example trace using `make trace examples`.
 
 Exported spans can be seen in zipkin at [http://127.0.0.1:9411](http://127.0.0.1:9411)