diff --git a/reference/sockets/functions/socket-write.xml b/reference/sockets/functions/socket-write.xml
index c46930e318..62bbac459b 100644
--- a/reference/sockets/functions/socket-write.xml
+++ b/reference/sockets/functions/socket-write.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- splitted from ./en/functions/sockets.xml, last change in rev 1.27 -->
   <refentry id="function.socket-write">
    <refnamediv>
@@ -10,24 +10,53 @@
     <title>Description</title>
      <methodsynopsis>
       <type>int</type><methodname>socket_write</methodname>
-      <methodparam><type>resource</type><parameter>socket_des</parameter></methodparam>
-      <methodparam><type>string</type><parameter>&amp;buffer</parameter></methodparam>
-      <methodparam><type>int</type><parameter>length</parameter></methodparam>
+      <methodparam><type>resource</type><parameter>socket</parameter></methodparam>
+      <methodparam><type>string</type><parameter>buffer</parameter></methodparam>
+      <methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam>
      </methodsynopsis>
-	&warn.experimental.func;
+    &warn.experimental.func;
     <para>
      The function <function>socket_write</function> writes to the socket 
-     <parameter>socket_des</parameter> from
-     <parameter>&amp;buffer</parameter> the number of bytes set by
-     <parameter>length</parameter>.
+     <parameter>socket</parameter> from
+     <parameter>buffer</parameter>.
     </para>
+    <para>
+     The optional parameter <parameter>length</parameter> can specify an
+     alternate length of bytes written to the socket. If this length is
+     greater then the buffer length, it is silently truncated to the length of
+     the buffer.
+    </para>
+    <para>
+     Returns the number of bytes successfully written to the socket or &false;
+     one error. The error code can be retrieved with
+     <function>socket_last_error</function>. This code may be passed to
+     <function>socket_strerror</function> to get a textual explanation of the
+     error.
+    </para>
+    <note>
+     <para>
+      <function>socket_write</function> does not necessarily write all bytes
+      from the given buffer. It's valid that, depending on the network
+      buffers etc., only a certain amount of data, even one byte, is written
+      though your buffer is greater. You have to watch out so you don't
+      unintentionally forget to transmit the rest of your data.
+     </para>
+    </note>
+    <note>
+     <para>
+      It is perfectly valid for <function>socket_write</function> to
+      return zero which means no bytes have been written. Be sure to use the
+      <literal>===</literal> operator to check for &false; in case of an
+      error.
+     </para>
+    </note>
     <para>
      See also 
      <function>socket_accept</function>,
      <function>socket_bind</function>,
      <function>socket_connect</function>,
      <function>socket_listen</function>,
-     <function>socket_read</function>, and
+     <function>socket_read</function> and
      <function>socket_strerror</function>.
     </para>
    </refsect1>