diff --git a/doc/Makefile b/doc/Makefile
deleted file mode 100644
index e30fc038..00000000
--- a/doc/Makefile
+++ /dev/null
@@ -1,5 +0,0 @@
-.PHONY: all
-all: ownership.svg
-
-%.svg: %.dot
- dot -Grankdir=LR -Tsvg -o $@ $<
diff --git a/doc/README.md b/doc/README.md
index 41963ae9..a85736de 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -1,11 +1,22 @@
# Logical Component Relationships
- Vertices are components.
-- Edges are ownership relationships between components. Each edge is labeled by the kind of "smart
- pointer" that could implement that kind of relationship.
-- Components containing a padlock are protected by a mutex.
-
-
+- Edges are ownership relationships between components. Each edge is labeled by the kind of pointer
+ that is used to implement the relationship.
+- Components with a padlock are protected by a mutex.
+
+```mermaid
+---
+title: Components Relationships
+config:
+ layout: elk
+---
+graph LR;
+ Tracer(Tracer) & TraceSegment("TraceSegment 🔒")-- shared -->Collector("Collector 🔒") & SpanSampler("SpanSampler 🔒") & TraceSampler("TraceSampler 🔒")
+ TraceSegment-- "`**unique**`" -->SpanData(SpanData)
+ Span(Span)-- shared -->TraceSegment
+ Span-- "`**raw**`" -->SpanData
+```
## Objects
diff --git a/doc/maintainers.md b/doc/maintainers.md
index e8dd0e4e..3247e561 100644
--- a/doc/maintainers.md
+++ b/doc/maintainers.md
@@ -106,8 +106,8 @@ that accompany handle-to-interface are avoided.
A "trace" is the entire tree of spans having the same trace ID.
-Within one process/worker/service, though, typically there is not an entire trace but only part of
-the trace. Let's call the process/worker/service a "tracer."
+Within one process / worker / service, though, typically there is not an entire trace but only part
+of the trace. Let's call the process / worker / service a "tracer."
One portion of a trace that's passing through the tracer is called a "trace segment." A trace
segment begins either at the trace's root span or at a span extracted from trace context, e.g. a
@@ -116,13 +116,20 @@ segment includes all local descendants of that span, and has as its "boundary" a
without children or descendant spans that were used to inject trace context out-of-tracer, e.g. in
outgoing HTTP request headers.
-There might be more than one trace segment for the _same trace_ within a tracer at the same time.
-Consider the diagram below.
-
-
-
-If our tracer is "service X," then this trace passes through the tracer twice. We would have two
-concurrent trace segments for the same trace.
+There might be more than one trace segment for the _same trace_ within a tracer. For example, in the
+diagram below, the trace passes through the "Service A" tracer twice. So for this trace, this tracer
+has two trace segments:
+
+```mermaid
+block
+ columns 8
+ a["root"]:8
+ space b["Service A - Trace segment A1 - Span A1"]:6 space
+ space:2 c["Service A - Trace segment A1 - Span A2"] d["Service A - Trace segment A1 - Span A3"]:4 space
+ space:3 e["Service B"]:3 space:2
+ space:4 f["Service A - Trace segment A2 - Span A4"]:2 space:2
+ space:4 g["Service A - Trace segment A2 - Span A5"] h["Service A - Trace segment A2 - Span A6"] space:2
+```
`class TraceSegment` is defined in [trace_segment.h](../include/datadog/trace_segment.h).
`TraceSegment` objects are managed internally by the library. That is to say, a user never creates a
diff --git a/doc/ownership.dot b/doc/ownership.dot
deleted file mode 100644
index 3889c67d..00000000
--- a/doc/ownership.dot
+++ /dev/null
@@ -1,25 +0,0 @@
-# This describes the object ownership relationships among the components
-# in the tracer library.
-#
-# Each vertex (node) is a component, while each edge is a relationship.
-# Edges are labeled by the kind of "smart pointer" that describes the
-# relationship, e.g. "Tracer holds a shared_ptr to SpanSampler," or
-# "Span holds a raw pointer to SpanData."
-#
-# Vertices labeled with a 🔒 are protected by a mutex.
-#
-digraph {
- rankdir=LR;
-
- Tracer -> "Collector 🔒" [label=" shared", fontsize=8];
- Tracer -> "SpanSampler 🔒" [label=" shared", fontsize=8];
- Tracer -> "TraceSampler 🔒" [label=" shared", fontsize=8];
-
- Span -> "TraceSegment 🔒" [label=" shared", fontsize=8];
- Span -> SpanData [label=< raw >, fontsize=8];
-
- "TraceSegment 🔒" -> SpanData [label=< unique >, fontsize=8];
- "TraceSegment 🔒" -> "Collector 🔒" [label=" shared", fontsize=8];
- "TraceSegment 🔒" -> "SpanSampler 🔒" [label=" shared", fontsize=8];
- "TraceSegment 🔒" -> "TraceSampler 🔒" [label=" shared", fontsize=8];
-}
diff --git a/doc/ownership.svg b/doc/ownership.svg
deleted file mode 100644
index e39c39de..00000000
--- a/doc/ownership.svg
+++ /dev/null
@@ -1,122 +0,0 @@
-
-
-
-
-
diff --git a/doc/segments.jpg b/doc/segments.jpg
deleted file mode 100644
index b8937998..00000000
Binary files a/doc/segments.jpg and /dev/null differ
-
-If our tracer is "service X," then this trace passes through the tracer twice. We would have two
-concurrent trace segments for the same trace.
+There might be more than one trace segment for the _same trace_ within a tracer. For example, in the
+diagram below, the trace passes through the "Service A" tracer twice. So for this trace, this tracer
+has two trace segments:
+
+```mermaid
+block
+ columns 8
+ a["root"]:8
+ space b["Service A - Trace segment A1 - Span A1"]:6 space
+ space:2 c["Service A - Trace segment A1 - Span A2"] d["Service A - Trace segment A1 - Span A3"]:4 space
+ space:3 e["Service B"]:3 space:2
+ space:4 f["Service A - Trace segment A2 - Span A4"]:2 space:2
+ space:4 g["Service A - Trace segment A2 - Span A5"] h["Service A - Trace segment A2 - Span A6"] space:2
+```
`class TraceSegment` is defined in [trace_segment.h](../include/datadog/trace_segment.h).
`TraceSegment` objects are managed internally by the library. That is to say, a user never creates a
diff --git a/doc/ownership.dot b/doc/ownership.dot
deleted file mode 100644
index 3889c67d..00000000
--- a/doc/ownership.dot
+++ /dev/null
@@ -1,25 +0,0 @@
-# This describes the object ownership relationships among the components
-# in the tracer library.
-#
-# Each vertex (node) is a component, while each edge is a relationship.
-# Edges are labeled by the kind of "smart pointer" that describes the
-# relationship, e.g. "Tracer holds a shared_ptr to SpanSampler," or
-# "Span holds a raw pointer to SpanData."
-#
-# Vertices labeled with a 🔒 are protected by a mutex.
-#
-digraph {
- rankdir=LR;
-
- Tracer -> "Collector 🔒" [label=" shared", fontsize=8];
- Tracer -> "SpanSampler 🔒" [label=" shared", fontsize=8];
- Tracer -> "TraceSampler 🔒" [label=" shared", fontsize=8];
-
- Span -> "TraceSegment 🔒" [label=" shared", fontsize=8];
- Span -> SpanData [label=< raw >, fontsize=8];
-
- "TraceSegment 🔒" -> SpanData [label=< unique >, fontsize=8];
- "TraceSegment 🔒" -> "Collector 🔒" [label=" shared", fontsize=8];
- "TraceSegment 🔒" -> "SpanSampler 🔒" [label=" shared", fontsize=8];
- "TraceSegment 🔒" -> "TraceSampler 🔒" [label=" shared", fontsize=8];
-}
diff --git a/doc/ownership.svg b/doc/ownership.svg
deleted file mode 100644
index e39c39de..00000000
--- a/doc/ownership.svg
+++ /dev/null
@@ -1,122 +0,0 @@
-
-
-
-
-
diff --git a/doc/segments.jpg b/doc/segments.jpg
deleted file mode 100644
index b8937998..00000000
Binary files a/doc/segments.jpg and /dev/null differ