diff --git a/docs/libssh2_poll.3 b/docs/libssh2_poll.3
index fed831f..8377d1d 100644
--- a/docs/libssh2_poll.3
+++ b/docs/libssh2_poll.3
@@ -8,7 +8,9 @@ libssh2_poll - poll for activity on a socket, channel or listener
 
 int libssh2_poll(LIBSSH2_POLLFD *fds, unsigned int nfds, long timeout);
 .SH DESCRIPTION
-This function is deprecated. Do note use.
+This function is deprecated. Do note use. We encourage users to instead use
+the \fIpoll(3)\fP or \fIselect(3)\fP functions to check for socket activity or
+when specific sockets are ready to get recevied from or send to.
 
 Poll for activity on a socket, channel, listener, or any combination of these
 three types. The calling semantics for this function generally match