diff --git a/src/os/error.go b/src/os/error.go
index 7cd9f22bfb..704a6fb29e 100644
--- a/src/os/error.go
+++ b/src/os/error.go
@@ -76,6 +76,9 @@ func NewSyscallError(syscall string, err error) error {
 // IsExist returns a boolean indicating whether the error is known to report
 // that a file or directory already exists. It is satisfied by ErrExist as
 // well as some syscall errors.
+//
+// This function predates errors.Is. It only supports errors returned by
+// the os package. New code should use errors.Is(err, os.ErrExist).
 func IsExist(err error) bool {
 	return underlyingErrorIs(err, ErrExist)
 }
@@ -83,6 +86,9 @@ func IsExist(err error) bool {
 // IsNotExist returns a boolean indicating whether the error is known to
 // report that a file or directory does not exist. It is satisfied by
 // ErrNotExist as well as some syscall errors.
+//
+// This function predates errors.Is. It only supports errors returned by
+// the os package. New code should use errors.Is(err, os.ErrNotExist).
 func IsNotExist(err error) bool {
 	return underlyingErrorIs(err, ErrNotExist)
 }
@@ -90,12 +96,21 @@ func IsNotExist(err error) bool {
 // IsPermission returns a boolean indicating whether the error is known to
 // report that permission is denied. It is satisfied by ErrPermission as well
 // as some syscall errors.
+//
+// This function predates errors.Is. It only supports errors returned by
+// the os package. New code should use errors.Is(err, os.ErrPermission).
 func IsPermission(err error) bool {
 	return underlyingErrorIs(err, ErrPermission)
 }
 
 // IsTimeout returns a boolean indicating whether the error is known
 // to report that a timeout occurred.
+//
+// This function predates errors.Is, and the notion of whether an
+// error indicates a timeout can be ambiguous. For example, the Unix
+// error EWOULDBLOCK sometimes indicates a timeout and sometimes does not.
+// New code should use errors.Is with a value appropriate to the call
+// returning the error, such as os.ErrDeadlineExceeded.
 func IsTimeout(err error) bool {
 	terr, ok := underlyingError(err).(timeout)
 	return ok && terr.Timeout()