diff --git a/core/io/files/files-docs.factor b/core/io/files/files-docs.factor
index 7948a2e912..263b5c19b0 100644
--- a/core/io/files/files-docs.factor
+++ b/core/io/files/files-docs.factor
@@ -22,16 +22,19 @@ ABOUT: "io.files"
 HELP: <file-reader>
 { $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "stream" "an input stream" } }
 { $description "Outputs an input stream for reading from the specified pathname using the given encoding." }
+{ $notes "Most code should use " { $link with-file-reader } " instead, to ensure the stream is properly disposed of after." }
 { $errors "Throws an error if the file is unreadable." } ;
 
 HELP: <file-writer>
 { $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "stream" "an output stream" } }
 { $description "Outputs an output stream for writing to the specified pathname using the given encoding. The file's length is truncated to zero." }
+{ $notes "Most code should use " { $link with-file-writer } " instead, to ensure the stream is properly disposed of after." }
 { $errors "Throws an error if the file cannot be opened for writing." } ;
 
 HELP: <file-appender>
 { $values { "path" "a pathname string" } { "encoding" "an encoding descriptor" } { "stream" "an output stream" } }
 { $description "Outputs an output stream for writing to the specified pathname using the given encoding. The stream begins writing at the end of the file." }
+{ $notes "Most code should use " { $link with-file-appender } " instead, to ensure the stream is properly disposed of after." }
 { $errors "Throws an error if the file cannot be opened for writing." } ;
 
 HELP: with-file-reader