diff --git a/gui-doc/scribblings/gui/editor-intf.scrbl b/gui-doc/scribblings/gui/editor-intf.scrbl
index 459e20a8c..d717c1b92 100644
--- a/gui-doc/scribblings/gui/editor-intf.scrbl
+++ b/gui-doc/scribblings/gui/editor-intf.scrbl
@@ -1961,8 +1961,7 @@ See @method[editor<%> read-header-from-file].
            boolean?]{
 
 Reads new contents for the editor from a stream. The return value is
- @racket[#t] if there are no errors, @racket[#f] otherwise. See also
- @|filediscuss|.
+ @racket[#t] if there are no errors, @racket[#f] otherwise.
 
 The stream provides either new mappings for names in the editor's
  style list, or it indicates that the editor should share a
@@ -1982,6 +1981,29 @@ The stream provides either new mappings for names in the editor's
  the previously-read list.}
 
 ]
+
+Leveraging @method[editor<%> read-from-file] to read from the editor stream
+ requires some ceremony which may not be obvious at first; calls to
+ @racket[read-editor-global-header] and @racket[read-editor-global-footer]
+ must bracket any call to @method[editor<%> read-from-file], and only one
+ stream at a time can be read from using these methods or written to using
+ @racket[write-editor-global-header] and @racket[write-editor-global-footer].
+ See also @|filediscuss|.
+
+As a complete example consider the following:
+@racketblock[
+  (define (deserialize-text byte-stream)
+    (define editor (new text% [auto-wrap #t]))
+    (define editor-stream-in-bytes-base
+      (make-object editor-stream-in-bytes-base% byte-stream))
+    (define editor-stream-in
+      (make-object editor-stream-in% editor-stream-in-bytes-base))
+    (read-editor-global-header editor-stream-in)
+    (send editor read-from-file editor-stream-in)
+    (read-editor-global-footer editor-stream-in)
+    editor)
+]
+
 }
 
 
@@ -2651,11 +2673,32 @@ Does nothing.
            boolean?]{
 
 Writes the current editor contents to the given stream.  The return
- value is @racket[#t] if there are no errors, @racket[#f] otherwise. See
- also @|filediscuss|.
+ value is @racket[#t] if there are no errors, @racket[#f] otherwise.
 
 If the editor's style list has already been written to the stream, it
  is not re-written. Instead, the editor content indicates that the
  editor shares a previously-written style list. This sharing will be
  recreated when the stream is later read.
+
+Leveraging @method[editor<%> write-to-file] to write to the editor stream
+ requires some ceremony which may not be obvious at first; calls to
+ @racket[write-editor-global-header] and @racket[write-editor-global-footer]
+ must bracket any call to @method[editor<%> write-to-file], and only one
+ stream at a time can be written to using these methods or read from using
+ @racket[read-editor-global-header] and @racket[read-editor-global-footer].
+ See also @|filediscuss|.
+
+As a complete example consider the following:
+@racketblock[
+  (define (serialize-text text)
+    (define editor-stream-out-bytes-base
+      (new editor-stream-out-bytes-base%))
+    (define editor-stream-out
+      (make-object editor-stream-out% editor-stream-out-bytes-base))
+    (write-editor-global-header editor-stream-out)
+    (send text write-to-file editor-stream-out)
+    (write-editor-global-footer editor-stream-out)
+    (send editor-stream-out-bytes-base get-bytes))
+]
+
 }}