diff --git a/ChangeLog b/ChangeLog
index 13ba69e..5352f6d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -34,6 +34,8 @@
      MBEDTLS_ASN1_PARSE_C is not enabled. This allows the use of PBKDF2
      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.1.11 branch released 2018-03-16
 
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index 5f1bf79..5164460 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -2229,7 +2229,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