diff --git a/ChangeLog b/ChangeLog
index a8bfd92405..a25e505aa7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2006-07-26  Tim-Philipp Müller  <tim at centricular dot net>
+
+	* docs/manual/basics-elements.xml:
+	  Fix gst_element_link() example.
+
+	* gst/gstutils.c:
+	  Mention in API docs that one should usually gst_bin_add()
+	  elements to a bin or pipeline before doing the linking.
+	  
 2006-07-26  Wim Taymans  <wim@fluendo.com>
 
 	* gst/gstbuffer.c: (gst_buffer_get_type), (gst_buffer_new),
diff --git a/docs/manual/basics-elements.xml b/docs/manual/basics-elements.xml
index eccd6f9d93..41dffa2bcb 100644
--- a/docs/manual/basics-elements.xml
+++ b/docs/manual/basics-elements.xml
@@ -430,18 +430,27 @@ int
 main (int   argc,
       char *argv[])
 {
+  GstElement *pipeline;
   GstElement *source, *filter, *sink;
 
   /* init */
   gst_init (&amp;argc, &amp;argv);
 
+  /* create pipeline */
+  pipeline = gst_pipeline_new ("my-pipeline");
+
   /* create elements */
   source = gst_element_factory_make ("fakesrc", "source");
   filter = gst_element_factory_make ("identity", "filter");
   sink = gst_element_factory_make ("fakesink", "sink");
 
+  /* must add elements to pipeline before linking them */
+  gst_bin_add_many (GST_BIN (pipeline), source, filter, sink, NULL);
+
   /* link */
-  gst_element_link_many (source, filter, sink, NULL);
+  if (!gst_element_link_many (source, filter, sink, NULL)) {
+    g_warning ("Failed to link elements!");
+  }
 <!-- example-end elementlink.c a -->
 [..]<!-- example-begin elementlink.c b --><!--
   return 0;
@@ -457,6 +466,14 @@ main (int   argc,
       <function>gst_pad_link_* ()</function> functions. See the API
       references for more details.
     </para>
+    <para>
+      Important: you must add elements to a bin or pipeline
+      <emphasis>before</emphasis> linking them, since adding an element to
+      a bin will disconnect any already existing links. Also, you cannot
+      directly link elements that are not in the same bin or pipeline; if
+      you want to link elements or pads at different hierarchy levels, you
+      will need to use ghost pads (more about ghost pads later).
+    </para>
   </sect1>
 
   <sect1 id="section-elements-states">
diff --git a/gst/gstutils.c b/gst/gstutils.c
index f6f9d38115..23dab25297 100644
--- a/gst/gstutils.c
+++ b/gst/gstutils.c
@@ -1617,6 +1617,9 @@ gst_element_link_pads_filtered (GstElement * src, const gchar * srcpadname,
  * existing pads that aren't linked yet. It will request new pads if necessary.
  * If multiple links are possible, only one is established.
  *
+ * Make sure you have added your elements to a bin or pipeline with
+ * gst_bin_add() before trying to link them.
+ *
  * Returns: TRUE if the elements could be linked, FALSE otherwise.
  */
 gboolean
@@ -1632,6 +1635,8 @@ gst_element_link (GstElement * src, GstElement * dest)
  * @...: the NULL-terminated list of elements to link in order.
  *
  * Chain together a series of elements. Uses gst_element_link().
+ * Make sure you have added your elements to a bin or pipeline with
+ * gst_bin_add() before trying to link them.
  *
  * Returns: TRUE on success, FALSE otherwise.
  */
@@ -1670,6 +1675,9 @@ gst_element_link_many (GstElement * element_1, GstElement * element_2, ...)
  * existing pads that aren't linked yet. It will request new pads if necessary.
  * If multiple links are possible, only one is established.
  *
+ * Make sure you have added your elements to a bin or pipeline with
+ * gst_bin_add() before trying to link them.
+ *
  * Returns: TRUE if the pads could be linked, FALSE otherwise.
  */
 gboolean