diff --git a/ChangeLog b/ChangeLog
index aaf34fcef..c3db58771 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -54,6 +54,8 @@ Changes
      Wilson #481
    * Improve the documentation of mbedtls_net_accept(). Contributed by Ivan
      Krylov.
+   * Improve the documentation of mbedtls_ssl_write(). Suggested by
+     Paul Sokolovsky in #1356.
 
 = mbed TLS 2.8.0 branch released 2018-03-16
 
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index f7a1a013d..e1d64b9ce 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -2537,7 +2537,9 @@ int mbedtls_ssl_read( mbedtls_ssl_context *ssl, unsigned char *buf, size_t len )
  *
  * \note           When this function returns MBEDTLS_ERR_SSL_WANT_WRITE/READ,
  *                 it must be called later with the *same* arguments,
- *                 until it returns a positive value.
+ *                 until it returns a positive value. When the function returns
+ *                 MBEDTLS_ERR_SSL_WANT_WRITE there may be some partial
+ *                 data in the output buffer, however this is not yet sent.
  *
  * \note           If the requested length is greater than the maximum
  *                 fragment length (either the built-in limit or the one set