diff --git a/ChangeLog b/ChangeLog
index 9a63525..71e2e03 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -41,6 +41,8 @@
      without PBES2. Fixed by Marcos Del Sol Vives.
    * 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.7.2 branch released 2018-03-16
 
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index 0c4b3b5..e2f16b1 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -2520,7 +2520,9 @@
  *
  * \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