diff --git a/docs/tutorials/write-an-adapter.md b/docs/tutorials/write-an-adapter.md
index b37675ad9..6942c87e2 100644
--- a/docs/tutorials/write-an-adapter.md
+++ b/docs/tutorials/write-an-adapter.md
@@ -165,9 +165,18 @@ Note that all metadata should be nested inside a sub-dictionary (in this example
 Clip media (if known) should be linked like this:
 ```python
 clip.media_reference = otio.schema.ExternalReference(
-    target_url="file://example/movie.mov"
+    target_url=otio.url_utils.url_from_filepath("/show/seq/shot/movie.mov")
 )
 ```
+Prefer `otio.url_utils.url_from_filepath()` over building the `file://` URL by
+hand (e.g. `"file://" + path`). A hand-built URL is easy to get subtly wrong —
+for example `"file://" + "/show/movie.mov"` yields `file:///show/movie.mov`
+correctly, but `"file://" + "show/movie.mov"` (no leading slash, or a
+Windows-style path like `C:\show\movie.mov`) produces a URL whose first path
+segment is parsed as the host per [RFC 3986](https://tools.ietf.org/html/rfc3986#section-2.1),
+silently dropping part of the path. `url_from_filepath()` handles absolute vs.
+relative paths and Windows drive letters correctly, and its output round-trips
+through `otio.url_utils.filepath_from_url()`.
 
 Some formats don't support direct links to media, but focus on metadata instead. It is fine to leave the media_reference empty ('None') if your adapter doesn't know a real file path or URL for the media.
 
@@ -186,7 +195,7 @@ Note that the source_range of the clip is not necessarily the same as the availa
 If you know the range of media available at that Media Reference's URL, then you can specify it like this:
 ```python
 clip.media_reference = otio.schema.ExternalReference(
-  target_url="file://example/movie.mov",
+  target_url=otio.url_utils.url_from_filepath("/show/seq/shot/movie.mov"),
   available_range=otio.opentime.TimeRange(
       start_time=otio.opentime.RationalTime(100, 24), # frame 100 @ 24fps
       duration=otio.opentime.RationalTime(500, 24) # 500 frames @ 24fps
diff --git a/examples/conform.py b/examples/conform.py
index 4d7bb7dba..2d5d852a4 100755
--- a/examples/conform.py
+++ b/examples/conform.py
@@ -109,7 +109,7 @@ def _conform_timeline(timeline, folder):
 
         # relink to the found path
         clip.media_reference = otio.schema.ExternalReference(
-            target_url="file://" + new_path,
+            target_url=otio.url_utils.url_from_filepath(new_path),
             available_range=None  # the available range is unknown without
                                   # opening the file
         )
diff --git a/examples/shot_detect.py b/examples/shot_detect.py
index ef46e04c1..a5dd071b8 100755
--- a/examples/shot_detect.py
+++ b/examples/shot_detect.py
@@ -108,7 +108,7 @@ def _timeline_with_single_clip(name, full_path, dryrun=False):
     available_range = _media_start_end_of(full_path, fps)
 
     media_reference = otio.schema.ExternalReference(
-        target_url="file://" + full_path,
+        target_url=otio.url_utils.url_from_filepath(full_path),
         available_range=available_range
     )
 
@@ -167,7 +167,7 @@ def _timeline_with_breaks(name, full_path, dryrun=False):
         available_range = _media_start_end_of(full_path, fps)
 
         clip.media_reference = otio.schema.ExternalReference(
-            target_url="file://" + full_path,
+            target_url=otio.url_utils.url_from_filepath(full_path),
             available_range=available_range
         )
         track.append(clip)