make README.md better

Author: xenolay

README.md

@@ -1,22 +1,21 @@
-Distributed Tracing Wrapper Libraries.
+This repository provides distributed tracing wrapper libraries which we use in our company. 
 
-# Aim of this libraries
+# Aim of these libraries
 
-- Provide unified/tested set of libraries
+- Provide unified/tested sets of libraries
   - No need to load/maintain various `contrib` libraries
-- Provide high-level & simple interface over tracing standard APIs (e.g. OpenCensus)
-  - No need to know detail of API
-  - Provides simple interface
-  - Hide complicated object lifecycle of APIs (hide error prone things from you)
+- Provide high-level & simple interfaces over tracing standard APIs (e.g. OpenCensus)
+  - No need to know details of APIs
+  - Provide simple interfaces
+  - Hide complicated object lifecycles of APIs (hide error prone things from you)
 
-# Non-goal of this libraries
+# Non-goal of these libraries
 
-- Do not aim to provide `agent`, _you need to activate/call this library explicitly_
-  - Do not prefer to use dynamic code rewriting / monkey patching to minimize risk
-  - To use feature of this library, please explicitly call/enable them
-- Do not aim to support all libraries in the world (HTTP client library, logging library, ...)
-  - Focus on use case in our company.
-  - If you want to add library support, feel free to fork this.
+- Do not aim to provide `agent`, _you need to activate/call these libraries explicitly_
+  - We do not prefer to use dynamic code rewriting / monkey patching
+- Do not aim to support all kinds of libraries in the world (HTTP client library, logging library, ...)
+  - We focus on usecases or scenarios appearing in our work.
+  - If you want to add any kinds of library support which is not supported by us, please feel free to fork this repository.
 
 # How to start
 
@@ -39,40 +38,37 @@ See [jvm/README](jvm/README.md).
 | Capture method invocation                    |                                               | method annotation AOP        | Play: ????              |
 | Dependency injection                         |                                               | AutoConfiguration (Boot)     | ????                    |
 
-Summary of each features are described below, but don't forget to see document of each language to see how to use/enable it.
+Summaries of each features are described below. Supplemental documents for each languages are provided to see how to use/enable them.
 
-## Feature: Capture incoming HTTP request
+## Feature: Capture incoming HTTP requests
 
-With this feature, this library automatically create trace/span for each incoming requests.
+A trace/span is automatically created for each incoming request.
 
-## Feature: Capture & Propagate to outgoing HTTP request
+## Feature: Capture & Propagate to outgoing HTTP requests
 
-With this feature:
-
-- This library create span for each outgoing requests
-  - So that you can know duration/summary of outgoing requests
+- The library creates one span for each outgoing request, which helps to know durations/summaries of your outgoing requests
 - This library adds `Trace ID` to outgoing HTTP requests
-  - If destination service uses this library, we can trace request over services (-> "distributed" tracing)
+  - If destination service uses this library, we can trace requests over services (-> "distributed" tracing)
 
 ## Feature: Capture database call
 
-With this feature, this library yield spans for each database call.
+The library yields spans for each database call.
 
 ## Feature: Multi-thread
 
-With this feature, this library wraps multi-thread (async) operations and propagate thread-bounded trace/span to threads.
+The library wraps multi-thread (async) operations and propagate thread-bounded trace/span to threads.
 
 ## Feature: Log correlation
 
-With this feature, you can output `Trace ID` in logs. So that you can find related logs from/to traces.
+You can output `Trace ID` in logs to distinguish which trace/span logs are related.
 
 ## Feature: Capture any method invocation
 
-With this feature, you can capture method call of your own class.
+You can capture method calls of your own classes.
 
 ## Feature: Dependency injection
 
-With this feature, this library provides DI configuration so that you can get objects from DI context.
+The library provides DI configuration so that you can get objects from DI context.
 
 ## Note: Jakarta namespace support
 

jvm/README.md

@@ -7,24 +7,24 @@ Load following libraries:
 - `com.m3.tracing:core`
 - `com.m3.tracing:opencensus`(If you want to use OpenCensus)
 
-And there are framework/library integrations, describe later.
+Application framework integrations (e.g. integration with Spring Boot) are provided, which are described later.
 
 
 ## Initialization
 
 ### Load SDK
 
-You need to specify tracing SDK to use.
+You need to specify which tracing SDK to use.
 
 To use OpenCensus, specify `com.m3.tracing.tracer.opencensus.M3OpenCensusTracer` into `M3_TRACER_FQCN` environment variable or `m3.tracer.fqcn` JVM system property.
 
-By default, it uses `com.m3.tracing.tracer.logging.M3LoggingTracer` that just output trace information into SLF4J logs. It is useful for local test or stubbing but not useful for production.
+By default, the library uses `com.m3.tracing.tracer.logging.M3LoggingTracer` that just outputs trace information into SLF4J logs. This setting is useful for local testing or stubbing but not for production purposes.
 
-See [M3TracerFactory](core/src/main/kotlin/com/m3/tracing/M3TracerFactory.kt) for detail of SDK loading mechanism.
+See [M3TracerFactory](core/src/main/kotlin/com/m3/tracing/M3TracerFactory.kt) for more details of SDK loading mechanisms.
 
 ### Configure SDK
 
-To use OpenCensus, don't forget to look [opencensus/README](opencensus/README.md). You need to set sampling ration explicitly.
+To use OpenCensus, don't forget to look at [opencensus/README](opencensus/README.md). You need to set sampling ratio explicitly.
 
 ## Integrate with application framework
 
@@ -34,48 +34,48 @@ Setup one or some of following integrations:
 
 Load `com.m3.tracing:spring-boot` dependency.
 
-It traces incoming HTTP request, outgoing HTTP request (with `RestTemplate`) and so on.
+It traces incoming HTTP requests, outgoing HTTP requests (with `RestTemplate`) and so on.
 
-See [spring-boot/README](spring-boot/README.md) how to use it.
+See [spring-boot/README](spring-boot/README.md).
 
 ### Spring Framework without Spring Boot (`com.m3.tracing:spring-web`)
 
 Load `com.m3.tracing:spring-web` dependency.
 
-See [spring-web/README](spring-web/README.md) how to use it.
+See [spring-web/README](spring-web/README.md).
 
 ### Servlet without any web framework (`com.m3.tracing:servlet`)
 
 Load `com.m3.tracing:serlvet` dependency.
 
-See [servlet/README](servlet/README.md) how to use it.
+See [servlet/README](servlet/README.md).
 
 ## Integrate with libraries
 
 ### JDBC (trace SQLs of RDBMS)
 
 You can use `com.m3.tracing:jdbc-p6spy` to capture SQLs via any JDBC driver.
 
-See [jdbc-p6spy/README](jdbc-p6spy/README.md) how to use it.
+See [jdbc-p6spy/README](jdbc-p6spy/README.md).
 
 ### Apache HttpClient
 
-You can use `com.m3.tracing:apache-httpclient` to trace outgoing HTTP request of Apache HttpClient.
+You can use `com.m3.tracing:apache-httpclient` to trace outgoing HTTP requests of Apache HttpClient.
 
-See [apache-httpclient/README](apache-httpclient/README.md) how to use it.
+See [apache-httpclient/README](apache-httpclient/README.md).
 
 
 # Create span by manual
 
 You can create span (element of trace) explicitly as like as:
 
 ```java
-// note: If you are using framework integration, may able to use DI (e.g. `@Autowired Tracer` in spring-boot)
+// note: If you are using framework integration, you might be able to use DI (e.g. `@Autowired Tracer` in spring-boot)
 private static final Tracer tracer = M3TracerFactory.get();
 
 void yourMethod() {
   // You MUST close span to prevent memory leak.
-  // Recommend to use try-with-resources (Java) or use (Kotlin).
+  // We recommend using try-with-resources (Java) or use (Kotlin).
   try(TraceSpan span = tracer.startSpan("do_something")){
     // ... do anything you want ...
 
@@ -84,24 +84,24 @@ void yourMethod() {
 }
 ```
 
-Also you can set custom tag to the span with `Span#set(tagName, value)` method.
+Also you can set custom tag to the span by `Span#set(tagName, value)` method.
 
 ## Caution for thread / asynchronous operation
 
-If your application perform operation over threads (e.g. using [Executor](https://docs.oracle.com/javase/jp/8/docs/api/java/util/concurrent/Executor.html), [Akka](https://akka.io/), ...), you need to propagate tracing context across threads.
+If your application performs an operation over multiple threads (e.g. using [Executor](https://docs.oracle.com/javase/jp/8/docs/api/java/util/concurrent/Executor.html), [Akka](https://akka.io/), ...), you need to propagate the tracing context across threads.
 
-Although this library hides context propagation matter as possible, but you need to write a code like this:
+Although this library hides context propagation matters as possible as it can, you need to write a code like this:
 
 ```java
 private static final Tracer tracer = M3TracerFactory.get();
 
 void yourMethod() {
-  // Parent thread should call getCurrentContext() before child thread's task.
+  // The parent thread should call getCurrentContext() before child thread's task.
   final TraceContext traceContext = tracer.getCurrentContext();
   executor.execute(() -> {
-    // In child thread, use traceContext.startSpan() to start span in the same context with parent
+    // In the child thread, use traceContext.startSpan() to start span in the same context as parent's one
     try(TraceSpan span = traceContext.startSpan("do_something")){
-      // ... do anything you want ...
+      // ... do something you want ...
     }
   });
 }