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>

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>

documentation/ref-manual/introduction.xml

@@ -12,29 +12,25 @@
         Welcome to the Yocto Project Reference Manual.
         This manual provides reference information for the current release
         of the Yocto Project.
-        The Yocto Project is an open-source collaboration project focused
-        on embedded Linux developers.
-        Amongst other things, the Yocto Project uses the OpenEmbedded build
-        system, which is based on the Poky project, to construct complete
-        Linux images.
+        This manual is best used after you have an understanding
+        of the basics of the Yocto Project.
+        The manual is neither meant to be read as a starting point to the
+        Yocto Project nor read from start to finish.
+        Use this manual to find concepts, variable definitions, class
+        descriptions, and so forth as needed during the course of using
+        the Yocto Project.
     </para>
 
     <para>
-        This reference manual is best used after you have an understanding
-        of the basics of the Yocto Project.
-        The manual is not meant to be read as a starting point to the
-        Yocto Project.
-        Use this manual to find concepts, variable definitions, class
-        descriptions, and so forth.
-        The manual augments working with the Yocto Project during application
-        and kernel development.
+        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>.
     </para>
 
     <para>
-        The Yocto Project Reference Manual does not provide "how-to",
-        task-oriented information.
-        You can find complete introductory and getting started information
-        on the Yocto Project by reading the
+        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>.
         You can find "how-to" information in the
         <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink>.
@@ -47,124 +43,37 @@
     </para>
 </section>
 
-<!--
-<section id='intro-manualoverview'>
-    <title>Documentation Overview</title>
+<section id='ref-yp-intro'>
+    <title>Yocto Project Introduction</title>
+
     <para>
-        This reference manual consists of the following:
-        <itemizedlist>
-            <listitem><para>
-                <emphasis>
-                <link linkend='usingpoky'>Using the Yocto Project</link>:
-                </emphasis>
-                Provides an overview of the components that make up the Yocto
-                Project followed by information about debugging images created
-                in the Yocto Project.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='closer-look'>A Closer Look at the Yocto Project Development Environment</link>:
-                </emphasis>
-                Provides a more detailed look at the Yocto Project development
-                environment within the context of development.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='technical-details'>Technical Details</link>:
-                </emphasis>
-                Describes fundamental Yocto Project components as well as an
-                explanation behind how the Yocto Project uses shared state
-                (sstate) cache to speed build time.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='migration'>Migrating to a Newer Yocto Project Release</link>:
-                </emphasis>
-                Describes release-specific information that helps you move from
-                one Yocto Project Release to another.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='ref-structure'>Directory Structure</link>:
-                </emphasis> Describes the
-                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
-                created either by unpacking a released Yocto Project tarball on
-                your host development system, or by cloning the upstream
-                <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink>
-                Git repository.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='ref-classes'>Classes</link>:
-                </emphasis>
-                Describes the classes used in the Yocto Project.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='ref-tasks'>Tasks</link>:
-                </emphasis>
-                Describes the tasks defined by the OpenEmbedded build system.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='ref-devtool-reference'><filename>devtool</filename> Quick Reference</link>:
-                </emphasis>
-                Provides a quick reference for the <filename>devtool</filename>
-                command.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='ref-qa-checks'>QA Error and Warning Messages</link>:
-                </emphasis>
-                Lists and describes QA warning and error messages.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='ref-images'>Images</link>:
-                </emphasis>
-                Describes the standard images that the Yocto Project supports.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='ref-features'>Features</link>:
-                </emphasis>
-                Describes mechanisms for creating distribution, machine, and
-                image features during the build process using the OpenEmbedded
-                build system.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='ref-variables-glos'>Variables Glossary</link>:
-                </emphasis>
-                Presents most variables used by the OpenEmbedded build system,
-                which uses BitBake.
-                Entries describe the function of the variable and how to
-                apply them.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='ref-varlocality'>Variable Context</link>:
-                </emphasis>
-                Provides variable locality or context.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='faq'>FAQ</link>:
-                </emphasis>
-                Provides answers for commonly asked questions in the Yocto
-                Project development environment.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='resources'>Contributions and Additional Information</link>:
-                </emphasis>
-                Provides an overview of methods by which you can
-                contribute to and participate in the Yocto Project.
-                </para></listitem>
-        </itemizedlist>
+        The Yocto Project is an open-source collaboration project whose
+        focus is for developers of embedded Linux systems.
+        Among other things, the Yocto Project uses a build host based
+        on the OpenEmbedded (OE) project, which uses the
+        <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
+        tool, to construct complete Linux images.
+        The BitBake and OE components are combined together to form
+        a reference build host, historically known as
+        <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink>
+        (<emphasis>Pah</emphasis>-kee).
+    </para>
+
+    <para>
+        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 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-your-own-distribution'>Creating Your Own Distribution</ulink>"
+        section in the Yocto Project Development Manual for more information.
     </para>
 </section>
--->
 
 <section id='intro-requirements'>
 <title>System Requirements</title>