dev-manual, ref-manual: Re-wrote the intros

Fixes [YOCTO #11630]

I updated both the introductory sections of the ref-manual and the
dev-manual.  These need to work more tightly with the projected
YP documentation set.

(From yocto-docs rev: 6a28537d03fad8a53198edc7f9a6229f4e58e551)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 53 insertions, 70 deletions

diff --git a/documentation/dev-manual/dev-manual-intro.xml b/documentation/dev-manual/dev-manual-intro.xml
index 945c83e2c3..8c94009335 100644
--- a/documentation/dev-manual/dev-manual-intro.xml
+++ b/documentation/dev-manual/dev-manual-intro.xml
@@ -10,96 +10,67 @@
 
         <para>
             Welcome to the Yocto Project Development Manual!
-            This manual provides information on how to use the Yocto Project to
-            develop embedded Linux images and user-space applications that
-            run on targeted devices.
-            The manual provides an overview of image, kernel, and
-            user-space application development using the Yocto Project.
-            Because much of the information in this manual is general, it
-            contains many references to other sources where you can find more
-            detail.
-            For example, you can find detailed information on Git, repositories,
-            and open source in general in many places on the Internet.
-            Another example specific to the Yocto Project is how to quickly
-            set up your host development system and build an image, which you
-            find in the
-            <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
-        </para>
-
-        <para>
-            The Yocto Project Development Manual does, however, provide
-            guidance and examples on how to change the kernel source code,
-            reconfigure the kernel, and develop an application using
-            <filename>devtool</filename>.
+            This manual provides relevant procedures necessary for developing
+            in the Yocto Project environment (i.e. developing embedded Linux
+            images and user-space applications that run on targeted devices).
+            The manual groups related procedures into higher-level sections.
+            Procedures can consist of high-level steps or low-level steps
+            depending on the topic.
+            You can find conceptual information related to a procedure by
+            following appropriate links to the Yocto Project Reference
+            Manual.
         </para>
 
-        <note>
-            By default, using the Yocto Project creates a Poky distribution.
-            However, you can create your own distribution by providing key
-            <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>.
-            A good example is Angstrom, which has had a distribution
-            based on the Yocto Project since its inception.
-            Other examples include commercial distributions like
-            <ulink url='https://www.yoctoproject.org/organization/wind-river-systems'>Wind River Linux</ulink>,
-            <ulink url='https://www.yoctoproject.org/organization/mentor-graphics'>Mentor Embedded Linux</ulink>,
-            <ulink url='https://www.yoctoproject.org/organization/enea-ab'>ENEA Linux</ulink>
-            and <ulink url='https://www.yoctoproject.org/ecosystem/member-organizations'>others</ulink>.
-            See the "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
-            section for more information.
-        </note>
-    </section>
-
-    <section id='what-this-manual-provides'>
-        <title>What This Manual Provides</title>
-
         <para>
             The following list describes what you can get from this manual:
             <itemizedlist>
-                <listitem><para>Information that lets you get set
-                    up to develop using the Yocto Project.</para></listitem>
-                <listitem><para>Information to help developers who are new to
-                    the open source environment and to the distributed revision
-                    control system Git, which the Yocto Project uses.
+                <listitem><para>
+                    <emphasis>Setup Procedures:</emphasis>
+                    Procedures that show you how to set
+                    up a Yocto Project Development environment and how
+                    to accomplish the change workflow through logging
+                    defects and submitting changes.
                     </para></listitem>
-                <listitem><para>An understanding of common end-to-end
-                    development models and tasks.</para></listitem>
-                <listitem><para>Information about common development tasks
-                    generally used during image development for
-                    embedded devices.
+                <listitem><para>
+                    <emphasis>Emulation Procedures:</emphasis>
+                    Procedures that show you how to use the
+                    Yocto Project integrated QuickEMUlator (QEMU), which lets
+                    you simulate running on hardware an image you have built
+                    using the OpenEmbedded build system.
                     </para></listitem>
-                <listitem><para>Information on using the Yocto Project
-                    integration of the QuickEMUlator (QEMU), which lets you
-                    simulate running on hardware an image you have built using
-                    the OpenEmbedded build system.
+                <listitem><para>
+                    <emphasis>Common Procedures:</emphasis>
+                    Procedures related to "everyday" tasks you perform while
+                    developing images and applications using the Yocto
+                    Project.
                     </para></listitem>
-                <listitem><para>Many references to other sources of related
-                    information.</para></listitem>
             </itemizedlist>
         </para>
-    </section>
-
-    <section id='what-this-manual-does-not-provide'>
-        <title>What this Manual Does Not Provide</title>
 
         <para>
             This manual will not give you the following:
             <itemizedlist>
-                <listitem><para><emphasis>Step-by-step instructions when those instructions exist in other Yocto
-                    Project documentation:</emphasis>
+                <listitem><para>
+                    <emphasis>Redundant Step-by-step Instructions:</emphasis>
                     For example, the
                     <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>
-                    manual contains detailed instructions on how to install an
+                    contains detailed instructions on how to install an
                     SDK, which is used to develop applications for target
                     hardware.
                     </para></listitem>
-                <listitem><para><emphasis>Reference material:</emphasis>
+                <listitem><para>
+                    <emphasis>Reference or Conceptual Material:</emphasis>
                     This type of material resides in an appropriate reference manual.
                     For example, system variables are documented in the
                     <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>.
                     </para></listitem>
-                <listitem><para><emphasis>Detailed public information that is not specific to the Yocto Project:</emphasis>
-                    For example, exhaustive information on how to use Git is covered better through the
-                    Internet than in this manual.
+                <listitem><para>
+                    <emphasis>Detailed Public Information Not Specific to the
+                    Yocto Project:</emphasis>
+                    For example, exhaustive information on how to use the
+                    Source Control Manager Git is better covered with Internet
+                    searches and official Git Documentation than through the
+                    Yocto Project documentation.
                     </para></listitem>
             </itemizedlist>
         </para>
@@ -112,10 +83,22 @@
             Because this manual presents information for many different
             topics, supplemental information is recommended for full
             comprehension.
-            See the
+            For introductory information on the Yocto Project, see the
+            <ulink url='&YOCTO_HOME_URL;/ecosystem/yocto-project-backgrounders'>Yocto Project Backgrounders</ulink>
+            on the
+            <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>.
+            You can find an introductory to using the Yocto Project by working
+            through the
+            <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
+        </para>
+
+        <para>
+            For a comprehensive list of links and other documentation, see the
             "<ulink url='&YOCTO_DOCS_REF_URL;#resources-links-and-related-documentation'>Links and Related Documentation</ulink>"
-            section in the Yocto Project Reference Manual for helpful
-            sources.
+            section in the Yocto Project Reference Manual.
+        </para>
+
+        <para>
         </para>
     </section>
 </chapter>