diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index fed25b25e6..54691ec9f6 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -2160,6 +2160,11 @@
         <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>,
         and
         <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>.
+        <note><title>Warning</title>
+            The <filename>package_tar</filename> class is broken and not
+            supported.
+            It is recommended that you do not use this class.
+        </note>
     </para>
 
     <para>
@@ -2298,6 +2303,12 @@
 <section id='ref-classes-package_tar'>
     <title><filename>package_tar.bbclass</filename></title>
 
+    <note><title>Warning</title>
+        The <filename>package_tar</filename> class is broken and is not
+        supported.
+        It is recommended that you do not use it.
+    </note>
+
     <para>
         The <filename>package_tar</filename>
         class provides support for creating packages that use the
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 281c4e3e2d..337c3f4397 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -4444,6 +4444,11 @@
                     or
                     <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
                     class.
+                    <note><title>Warning</title>
+                        The <filename>package_tar</filename> class is broken
+                        and is not supported.
+                        It is recommended that you do not use it.
+                    </note>
                 </para>
 
                 <para>
@@ -6932,6 +6937,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     <literallayout class='monospaced'>
      PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk package_tar"
                     </literallayout>
+                    <note><title>Warning</title>
+                        While it is a legal option, the
+                        <filename>package_tar</filename> class is broken
+                        and is not supported.
+                        It is recommended that you do not use it.
+                    </note>
                     The build system uses only the first argument in the list
                     as the package manager when creating your image or SDK.
                     However, packages will be created using any additional
@@ -6939,20 +6950,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     For example, if you use the following in your
                     <filename>local.conf</filename> file:
                     <literallayout class='monospaced'>
-     PACKAGE_CLASSES ?= "package_ipk package_tar"
+     PACKAGE_CLASSES ?= "package_ipk"
                     </literallayout>
                     The OpenEmbedded build system uses the IPK package manager
-                    to create your image or SDK as well as generating
-                    TAR packages.
-                </para>
-
-                <para>
-                    You cannot specify the
-                    <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
-                    class first in the list.
-                    Files using the <filename>.tar</filename> format cannot
-                    be used as a substitute packaging format
-                    for DEB, RPM, and IPK formatted files for your image or SDK.
+                    to create your image or SDK.
                 </para>
 
                 <para>