diff --git a/read_password_test.go b/read_password_test.go
new file mode 100644
index 0000000..b1eb3cd
--- /dev/null
+++ b/read_password_test.go
@@ -0,0 +1,21 @@
+// Copyright 2021 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package term_test
+
+import (
+	"fmt"
+	"os"
+
+	"golang.org/x/term"
+)
+
+func ExampleReadPassword() {
+	fmt.Print("Enter your password: ")
+	p, err := term.ReadPassword(int(os.Stdin.Fd()))
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("\nYou entered '%s'\n", string(p))
+}
diff --git a/read_password_unix_test.go b/read_password_unix_test.go
new file mode 100644
index 0000000..82170bf
--- /dev/null
+++ b/read_password_unix_test.go
@@ -0,0 +1,30 @@
+// Copyright 2021 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// +build !windows
+
+package term_test
+
+import (
+	"fmt"
+	"os"
+
+	"golang.org/x/term"
+)
+
+func ExampleReadPassword_unix() {
+	// If standard input is not bound to the terminal, a password can
+	// still be read from it.
+	tty, err := os.Open("/dev/tty")
+	if err != nil {
+		panic(err)
+	}
+	defer tty.Close()
+	fmt.Print("Enter your password: ")
+	p, err := term.ReadPassword(int(tty.Fd()))
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("\nYou entered '%s'\n", string(p))
+}
diff --git a/read_password_windows_test.go b/read_password_windows_test.go
new file mode 100644
index 0000000..a28af27
--- /dev/null
+++ b/read_password_windows_test.go
@@ -0,0 +1,40 @@
+// Copyright 2021 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// +build windows
+
+package term_test
+
+import (
+	"fmt"
+	"unsafe"
+
+	"golang.org/x/sys/windows"
+	"golang.org/x/term"
+)
+
+func ExampleReadPassword_windows() {
+	// If standard input is not bound to the terminal, a password can
+	// still be read from it.
+
+	path, err := windows.UTF16PtrFromString("CONIN$")
+	if err != nil {
+		panic(err)
+	}
+	var sa windows.SecurityAttributes
+	sa.Length = uint32(unsafe.Sizeof(sa))
+	sa.InheritHandle = 1
+	tty, err := windows.CreateFile(path, windows.GENERIC_READ|windows.GENERIC_WRITE, windows.FILE_SHARE_READ|windows.FILE_SHARE_WRITE, &sa, windows.OPEN_EXISTING, 0, 0)
+	if err != nil {
+		panic(err)
+	}
+	defer windows.CloseHandle(tty)
+
+	fmt.Print("Enter your password: ")
+	p, err := term.ReadPassword(int(tty))
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("\nYou entered '%s'\n", string(p))
+}