@@ -2578,32 +2578,6 @@ simply retry the request later. In the event a client detects a `ResponseStatusC
 which is error code `596`, the client may choose to retry that request. Note that drivers do not have the ability to
 automatically retry and that it is up to the application to provide such logic.
 
-[[testing-remote-providers]]
-==== Testing Remote Providers
-
-As of 3.7.0, it is recommended to use TinkerTransactionGraph, the transactional TinkerGraph, for testing, as it provides
-transactional capabilities on top of exiting TinkerGraph functionalities.
-
-To use TinkerTransactionGraph remotely, start a Gremlin Server with the `gremlin-server-transaction.yaml` config file.
-
-[source,java]
-----
-Cluster cluster = Cluster.build("localhost").port(8182).create();
-Client client = cluster.connect();
-GraphTraversalSource g = traversal().withRemote(DriverRemoteConnection.using(client, "g"));
-GraphTraversalSource gtx = g.tx().begin();
-
-try {
-  Vertex marko = gtx.addV("person").property("name","marko").property("age",29).next();
-  Vertex lop = gtx.addV("software").property("name","lop").property("lang","java").next();
-  gtx.addE("created").from(marko).to(lop).property("weight",0.6d).iterate();
-
-  gtx.tx().commit();
-} catch (Exception ex) {
-  gtx.tx().rollback();
-}
-----
-
 [[gremlin-server-docker-image]]
 === Docker Image
 
 
@@ -160,6 +160,9 @@ also be specified.  If this value is not included (default), then the graph will
 loaded/persisted to disk.
 |=========================================================
 
+NOTE: To use <<tinkergraph-gremlin-tx, transactions>>, configure `gremlin.graph` as
+`org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerTransactionGraph`.
+
 The `IdManager` settings above refer to how TinkerGraph will control identifiers for vertices, edges and vertex
 properties.  There are several options for each of these settings: `ANY`, `LONG`, `INTEGER`, `UUID`, or the fully
 qualified class name of an `IdManager` implementation on the classpath.  When not specified, the default values
@@ -199,59 +202,124 @@ g.io("data/tinkerpop-crew.kryo").read().iterate()
 g.V().properties()
 ----
 
+[[tinkergraph-gremlin-tx]]
 === Transactions
 
-As of 3.7.0, `TinkerGraph` includes optional transaction support and thread-safety through the `TinkerTransactionGraph`
-class. The default configuration of TinkerGraph remains non-transactional.
+`TinkerGraph` includes optional transaction support and thread-safety through the `TinkerTransactionGraph` class.
+The default configuration of TinkerGraph remains non-transactional.
+
+NOTE: This feature was first made available in TinkerPop 3.7.0.
 
 ==== Transaction Semantics
 
-TinkerTransactionGraph only has support for ThreadLocal transactions, so embedded graph transactions may not be fully
+`TinkerTransactionGraph` only has support for `ThreadLocal` transactions, so embedded graph transactions may not be fully
 supported. You can think of the transaction as belonging to a thread, any traversals executed within the same thread
 will share the same transaction even if you attempt to start a new transaction.
 
-TinkerTransactionGraph provides the `read committed` transaction isolation level. This means that it will always try to
+`TinkerTransactionGraph` provides the `read committed` transaction isolation level. This means that it will always try to
 guard against dirty reads. While you may notice stricter isolation semantics in some cases, you should not depend on
 this behavior as it may change in the future.
 
-TinkerTransactionGraph employs optimistic locking as its locking strategy. This reduces complexity in the design as
+`TinkerTransactionGraph` employs optimistic locking as its locking strategy. This reduces complexity in the design as
 there are fewer timeouts that the user needs to manage. However, a consequence of this approach is that a transaction
 will throw a `TransactionException` if two different transactions attempt to lock the same element (see "Best Practices"
 below).
 
-==== Use Cases
+[[testing-remote-providers]]
+==== Testing Remote Providers
 
 These transaction semantics described above may not fit use cases for some production scenarios that require strict
-ACID-like transactions. Therefore, it is recommended that TinkerTransactionGraph be used as a Graph for test
-environments where you still require access to a Graph that supports transactions. TinkerTransactionGraph does fully
-support TinkerPop's `Transaction` interface which still makes it a useful Graph for exploring the Transaction API.
+ACID-like transactions. Therefore, it is recommended that `TinkerTransactionGraph` be used as a `Graph` for test
+environments where you still require access to a `Graph` that supports transactions. `TinkerTransactionGraph` does fully
+support TinkerPop's `Transaction` interface which still makes it a useful `Graph` for exploring the
+<<transactions,Transaction API>>.
 
-Once you are ready to put your system into production then you can choose a Graph provider that has the
-transaction semantics that fit your application's needs.
+A common scenario where this sort of testing is helpful is with <<connecting-rgp, Remote Graph Providers>>, where
+developing unit tests might be hard against a graph service. Instead, configure `TinkerTransactionGraph`, either in an
+embedded style if using Java or with Gremlin Server for other cases.
+
+[source,java]
+----
+// consider this class that returns the results of some Gremlin. by constructing the
+// GraphService in a way that takes a GraphTraversalSource it becomes possible to
+// execute getPersons() under any graph system.
+public class GraphService {
+    private final GraphTraversalSource g;
+
+    public GraphService(GraphTraversalSource g) {
+        this.g = g;
+    }
+
+    public List<Vertex> getPersons() {
+        return g.V().hasLabel("person").toList();
+    }
+}
+
+// when writing tests for the GraphService it becomes possible to configure the test
+// to run in a variety of scenarios. here we decide that TinkerTransactionGraph is a
+// suitable test graph replacement for our actual production graph.
+public class GraphServiceTest {
+    private static final TinkerTransactionGraph graph = TinkerTransactionGraph().open();
+    private static final GraphTraversalSource g = traversal.withEmbedded(graph);
+    private static final GraphService service = new GraphService(g);
+
+    @Test
+    public void shouldGetPersons() {
+        final List<Vertex> persons = service.getPersons();
+        assertEquals(6, persons.size());
+    }
+}
+
+// or perhaps, since we're using a remote graph provider, we feel it would be better to
+// start Gremlin Server with a TinkerTransactionGraph configured using a docker container,
+// embedding it directly in our tests or running it as a separate process like:
+//
+// bin/gremlin-server.sh conf/gremlin-server-transaction.yaml
+//
+// and then connect to it with a driver in more of an integration test style. obviously,
+// with this approach you could also configure your production graph directly or use custom
+// build options to trigger different test configurations for a more dynamic approach
+public class GraphServiceTest {
+    private static final GraphTraversalSource g = traversal.withRemote(
+            new DriverRemoteConnection('ws://localhost:8182/gremlin'));
+    private static final GraphService service = new GraphService(g);
+
+    @Test
+    public void shouldGetPersons() {
+        final List<Vertex> persons = service.getPersons();
+        assertEquals(6, persons.size());
+    }
+}
+----
+
+WARNING: There can be subtle behavioral differences between TinkerGraph and the graph ultimately intended for use.
+Be aware of the differences when writing tests to ensure that you are testing behaviors of your applications
+appropriately.
 
 ==== Best Practices
 
-Errors can occur before a transaction gets committed. Specifically for TinkerTransactionGraph, you may encounter many
-`TransactionException`s in a highly concurrent environment due its optimistic approach to locking. Users should follow
-the try-catch-rollback pattern described in the
+Errors can occur before a transaction gets committed. Specifically for `TinkerTransactionGraph`, you may encounter many
+`TransactionException` errors in a highly concurrent environment due its optimistic approach to locking. Users should
+follow the try-catch-rollback pattern described in the
 link:https://tinkerpop.apache.org/docs/x.y.z/reference/#transactions[transactions] section in combination with
 exponential backoff based retries to mitigate this issue.
 
 ==== Performance Considerations
 
 While transactions impose minimal impact for mutating workloads, users should expect performance degradation for
 read-only work relative to the non-transactional configuration. However, its approach to locking
-(write-only, optimistic) and its in-memory nature, TinkerTransactionGraph is likely faster than other Graph
+(write-only, optimistic) and its in-memory nature, TinkerTransactionGraph is likely faster than other `Graph`
 implementations that support transactions.
 
 ==== Examples
 
-Constructing a simple graph using TinkerTransactionGraph in Java is presented below:
+Constructing a simple graph using `TinkerTransactionGraph` in Java is presented below:
 
 [source,java]
 ----
 Graph graph = TinkerTransactionGraph.open();
-GraphTraversalSource gtx = graph.tx().begin();
+g = traversal().withEmbedded(graph)
+GraphTraversalSource gtx = g.tx().begin();
 
 try {
   Vertex marko = gtx.addV("person").property("name","marko").property("age",29).next();
 
@@ -477,7 +477,7 @@ the <<connecting-gremlin-server,previous section>> with the exact same caveats p
 
 Despite leveraging TinkerPop protocols and drivers as being typical, RGPs are not required to do so to be considered
 TinkerPop-enabled. RGPs may well have their own drivers and protocols that may plug into
-<<gremlin-drivers-variants,Gremlin Language Variants> and may allow for more advanced options like better security,
+<<gremlin-drivers-variants,Gremlin Language Variants>> and may allow for more advanced options like better security,
 cluster awareness, batched requests or other features. The details of these different systems are outside the scope
 of this documentation, so be sure to consult their documentation for more information.
 
 
@@ -162,23 +162,29 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-2957[TINKERPOP-2957]
 
 ==== TinkerGraph Transactions
 
-===== Introduction
-
 Previously, there was no reference implementation provided for the `Transaction` API as this feature wasn't supported by
 TinkerGraph. Users were instead directed towards the Neo4jGraph provided in `neo4j-gremlin` if they wanted to get access
 to a `Graph` implementation that supported transactions. Unfortunately, the maintenance around this plugin has largely
 been abandoned and is only compatible with Neo4j version 3.4, which reached end of life in March 2020.
 
-As of this version, we are introducing the transactional TinkerGraph, TinkerTransactionGraph, which is TinkerGraph with
-transaction capabilities. The TinkerTransactionGraph has `read committed` isolation level, which is the same as the
+As of this version, we are introducing the transactional TinkerGraph, `TinkerTransactionGraph`, which is TinkerGraph with
+transaction capabilities. The `TinkerTransactionGraph` has `read committed` isolation level, which is the same as the
 Neo4jGraph provided in `neo4j-gremlin`. Only `ThreadLocal` transactions are implemented, therefore embedded graph
 transactions may not be fully supported. These transaction semantics may not fit the use case for some production
 scenarios that require strict ACID-like transactions. Therefore, it is recommended that TinkerTransactionGraph be used
 as a Graph for test environments where you still require support for transactions.
 
 ===== Usage examples
 
-To use TinkerTransactionGraph remotely, start a Gremlin Server with the `gremlin-server-transaction.yaml` config file.
+To use `TinkerTransactionGraph` remotely, start a Gremlin Server with the included `gremlin-server-transaction.yaml`
+config file.
+
+[source,bash]
+----
+bin/gremlin-server.sh conf/gremlin-server-transaction.yaml
+----
+
+Then to connect with Java:
 
 [source,java]
 ----
@@ -274,14 +280,15 @@ gremlin> g.V().valueMap()
 <4> Add a second vertex without committing
 <5> Rollback the change
 
-Note that all embedded TinkerTransactionGraph remains ThreadLocal transactions, meaning that all traversal sources spawn
-from the graph will operate within the same transaction scope.
+Note that all embedded `TinkerTransactionGraph` remains `ThreadLocal` transactions, meaning that all traversal sources
+spawned from the graph will operate within the same transaction scope.
 
-===== Limitations
-At this point, the transactional TinkerGraph comes with performance limitations and thus is only meant for testing
-and not for production use.
+IMPORTANT: `TinkerTransactionGraph` comes with performance and semantic limitations, where the former is expect to
+be resolved in future versions. Since its primary recommended use case is for testing these limitations should not be
+an impediment. Production use cases for TinkerGraph should generally prefer the non-transactional implementation.
 
-Addition documentation can be found in <<transactions,Transactions>> section.
+See: link:https://issues.apache.org/jira/browse/TINKERPOP-2975[TINKERPOP-2975],
+link:https://tinkerpop.apache.org/docs/3.7.0/reference/#tinkergraph-gremlin-tx[Reference Documentation - TinkerGraph Transactions]
 
 ==== Properties on Elements