dev-manual: Updated team development environment section.

Found several areas that needed improvement.  Made these
modifications.

(From yocto-docs rev: e2125363d39b9a54a371fc737cc9b55d66c9be59)

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

1 files changed, 113 insertions, 99 deletions

diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index d8726b4857..f72606553a 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -10,8 +10,10 @@
     This chapter provides procedures related to getting set up to use the
     Yocto Project.
     You can learn about creating a team environment that develops using the
-    Yocto Project, how to set up a build host, how to locate Yocto Project
-    source repositories, and how to create local Git repositories.
+    Yocto Project, how to set up a
+    <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>,
+    how to locate Yocto Project source repositories, and how to create local
+    Git repositories.
 </para>
 
 <section id="usingpoky-changes-collaborate">
@@ -19,69 +21,71 @@
 
     <para>
         It might not be immediately clear how you can use the Yocto
-        Project in a team development environment, or scale it for a large
-        team of developers.
+        Project in a team development environment, or how to scale it for a
+        large team of developers.
         One of the strengths of the Yocto Project is that it is extremely
         flexible.
         Thus, you can adapt it to many different use cases and scenarios.
-        However, these characteristics can cause a struggle if you are trying
+        However, this flexibility could cause difficulties if you are trying
         to create a working setup that scales across a large team.
     </para>
 
     <para>
         To help you understand how to set up this type of environment,
-        this section presents a procedure that gives you the information
-        to learn how to get the results you want.
+        this section presents a procedure that gives you information
+        that can help you get the results you want.
         The procedure is high-level and presents some of the project's most
         successful experiences, practices, solutions, and available
-        technologies that work well.
+        technologies that have proved to work well in the past.
         Keep in mind, the procedure here is a starting point.
-        You can build off it and customize it to fit any
+        You can build off these steps and customize the procedure to fit any
         particular working environment and set of practices.
         <orderedlist>
             <listitem><para>
                 <emphasis>Determine Who is Going to be Developing:</emphasis>
                 You need to understand who is going to be doing anything
                 related to the Yocto Project and what their roles would be.
-                Making this determination is essential to completing the
+                Making this determination is essential to completing
                 steps two and three, which are to get your equipment together
                 and set up your development environment's hardware topology.
                 </para>
 
                 <para>The following roles exist:
-                <itemizedlist>
-                    <listitem><para>
-                        <emphasis>Application Development:</emphasis>
-                        These types of developers do application level work
-                        on top of an existing software stack.
-                        </para></listitem>
-                    <listitem><para>
-                        <emphasis>Core System Development:</emphasis>
-                        These types of developers work on the contents of the
-                        operating system image itself.
-                        </para></listitem>
-                    <listitem><para>
-                        <emphasis>Build Engineer:</emphasis>
-                        This type of developer manages Autobuilders and
-                        releases.
-                        Not all environments need a Build Engineer.
-                        </para></listitem>
-                    <listitem><para>
-                        <emphasis>Test Engineer:</emphasis>
-                        This type of developer creates and manages automated
-                        tests needed to ensure all application and core
-                        system development meets desired quality standards.
-                        </para></listitem>
-                </itemizedlist>
+                    <itemizedlist>
+                        <listitem><para>
+                            <emphasis>Application Developer:</emphasis>
+                            This type of developer does application level work
+                            on top of an existing software stack.
+                            </para></listitem>
+                        <listitem><para>
+                            <emphasis>Core System Developer:</emphasis>
+                            This type of developer works on the contents of the
+                            operating system image itself.
+                            </para></listitem>
+                        <listitem><para>
+                            <emphasis>Build Engineer:</emphasis>
+                            This type of developer manages Autobuilders and
+                            releases.
+                            Not all environments need a Build Engineer.
+                            </para></listitem>
+                        <listitem><para>
+                            <emphasis>Test Engineer:</emphasis>
+                            This type of developer creates and manages automated
+                            tests that are used to ensure all application and
+                            core system development meets desired quality
+                            standards.
+                            </para></listitem>
+                    </itemizedlist>
                 </para></listitem>
             <listitem><para>
                 <emphasis>Gather the Hardware:</emphasis>
                 Based on the size and make-up of the team, get the hardware
                 together.
-                Any development, build, or test engineer should be using
-                a system that is running a supported Linux distribution.
-                Systems, in general, should be high performance (e.g. dual,
-                six-core Xeons with 24 Gbytes of RAM and plenty of disk space).
+                Ideally, any development, build, or test engineer uses
+                a system that runs a supported Linux distribution.
+                These systems, in general, should be high performance
+                (e.g. dual, six-core Xeons with 24 Gbytes of RAM and plenty
+                of disk space).
                 You can help ensure efficiency by having any machines used
                 for testing or that run Autobuilders be as high performance
                 as possible.
@@ -107,11 +111,12 @@
                 <emphasis>Use Git as Your Source Control Manager (SCM):</emphasis>
                 Keeping your
                 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
-                and any software you are developing under the
-                control of an SCM system that is compatible
-                with the OpenEmbedded build system is advisable.
-                Of the SCMs BitBake supports, the
-                Yocto Project team strongly recommends using
+                (i.e. recipes, configuration files, classes, and so forth)
+                and any software you are developing under the control of an SCM
+                system that is compatible   with the OpenEmbedded build system
+                is advisable.
+                Of the SCMs BitBake supports, the Yocto Project team strongly
+                recommends using
                 <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>.
                 Git is a distributed system that is easy to backup,
                 allows you to work remotely, and then connects back to the
@@ -129,20 +134,19 @@
                 being used to generate the web interface that lets you view the
                 repositories.
                 The <filename>gitolite</filename> software identifies users
-                using SSH keys and allows branch-based
-                access controls to repositories that you can control as little
-                or as much as necessary.
-
+                using SSH keys and allows branch-based access controls to
+                repositories that you can control as little or as much as
+                necessary.
                 <note>
                    The setup of these services is beyond the scope of this
                    manual.
-                   However, sites such as these exist that describe how to
-                   perform setup:
+                   However, sites such as the following exist that describe
+                   how to perform setup:
                    <itemizedlist>
                        <listitem><para>
                            <ulink url='http://git-scm.com/book/ch4-8.html'>Git documentation</ulink>:
-                           Describes how to install <filename>gitolite</filename>
-                           on the server.
+                           Describes how to install
+                           <filename>gitolite</filename> on the server.
                            </para></listitem>
                        <listitem><para>
                            <ulink url='http://gitolite.com'>Gitolite</ulink>:
@@ -150,8 +154,8 @@
                             </para></listitem>
                         <listitem><para>
                             <ulink url='https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools'>Interfaces, frontends, and tools</ulink>:
-                            Documentation on how to create interfaces and frontends
-                            for Git.
+                            Documentation on how to create interfaces and
+                            frontends for Git.
                             </para></listitem>
                     </itemizedlist>
                 </note>
@@ -161,23 +165,22 @@
                 As mentioned earlier, application developers are creating
                 applications on top of existing software stacks.
                 Following are some best practices for setting up machines
-                that do application development:
+                used for application development:
                 <itemizedlist>
                     <listitem><para>
-                        Use a pre-built toolchain that
-                        contains the software stack itself.
+                        Use a pre-built toolchain that contains the software
+                        stack itself.
                         Then, develop the application code on top of the
                         stack.
                         This method works well for small numbers of relatively
                         isolated applications.
                         </para></listitem>
                     <listitem><para>
-                        When possible, use the Yocto Project
-                        plug-in for the
+                        When possible, use the Yocto Project plug-in for the
                         <trademark class='trade'>Eclipse</trademark> IDE
                         and SDK development practices.
                         For more information, see the
-                        "<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>"
+                        <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
                         manual.
                         </para></listitem>
                     <listitem><para>
@@ -186,27 +189,29 @@
                         toolchain downloads or as updates through a package
                         update mechanism using <filename>opkg</filename>
                         to provide updates to an existing toolchain.
-                        The exact mechanics of how and when to do this are a
-                        question for local policy.
+                        The exact mechanics of how and when to do this depend
+                        on local policy.
                         </para></listitem>
                     <listitem><para>
-                        Use multiple toolchains installed locally
-                        into different locations to allow development across
+                        Use multiple toolchains installed locally into
+                        different locations to allow development across
                         versions.
                         </para></listitem>
                 </itemizedlist>
                 </para></listitem>
             <listitem><para>
                 <emphasis>Set up the Core Development Machines:</emphasis>
-                As mentioned earlier, these types of developers work on the
-                contents of the operating system itself.
+                As mentioned earlier, core developers work on the contents of
+                the operating system itself.
                 Following are some best practices for setting up machines
                 used for developing images:
                 <itemizedlist>
                     <listitem><para>
-                        Have the Yocto Project build system itself available on
-                        the developer workstations so developers can run their own
-                        builds and directly rebuild the software stack.
+                        Have the
+                        <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
+                        available on the developer workstations so developers
+                        can run their own builds and directly rebuild the
+                        software stack.
                         </para></listitem>
                     <listitem><para>
                         Keep the core system unchanged as much as
@@ -228,8 +233,9 @@
                 Autobuilders are often the core of the development
                 environment.
                 It is here that changes from individual developers are brought
-                together and centrally tested and subsequent decisions about
-                releases can be made.
+                together and centrally tested.
+                Based on this automated build and test environment, subsequent
+                decisions about releases can be made.
                 Autobuilders also allow for "continuous integration" style
                 testing of software components and regression identification
                 and tracking.</para>
@@ -239,22 +245,23 @@
                 The Yocto Project team has found this implementation
                 works well in this role.
                 A public example of this is the Yocto Project
-                Autobuilders, which we use to test the overall health of the
-                project.</para>
+                Autobuilders, which the Yocto Project team uses to test the
+                overall health of the project.</para>
 
                 <para>The features of this system are:
                 <itemizedlist>
                     <listitem><para>
-                         Highlights when commits break the build.
-                         </para></listitem>
+                        Highlights when commits break the build.
+                        </para></listitem>
                     <listitem><para>
-                        Populates an sstate cache from which
-                        developers can pull rather than requiring local
-                        builds.
+                        Populates an
+                        <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>sstate cache</ulink>
+                        from which developers can pull rather than requiring
+                        local builds.
                         </para></listitem>
                     <listitem><para>
-                        Allows commit hook triggers,
-                        which trigger builds when commits are made.
+                        Allows commit hook triggers, which trigger builds when
+                        commits are made.
                         </para></listitem>
                     <listitem><para>
                         Allows triggering of automated image booting
@@ -275,19 +282,19 @@
                         Allows scheduling of builds so that resources
                         can be used efficiently.
                         </para></listitem>
-               </itemizedlist>
-               </para></listitem>
-           <listitem><para>
-               <emphasis>Set up Test Machines:</emphasis>
-               Use a small number of shared, high performance systems
-               for testing purposes.
-               Developers can use these systems for wider, more
-               extensive testing while they continue to develop
-               locally using their primary development system.
-               </para></listitem>
-           <listitem><para>
-               <emphasis>Document Policies and Change Flow:</emphasis>
-               The Yocto Project itself uses a hierarchical structure and a
+                </itemizedlist>
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Set up Test Machines:</emphasis>
+                Use a small number of shared, high performance systems
+                for testing purposes.
+                Developers can use these systems for wider, more
+                extensive testing while they continue to develop
+                locally using their primary development system.
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Document Policies and Change Flow:</emphasis>
+                The Yocto Project uses a hierarchical structure and a
                 pull model.
                 Scripts exist to create and send pull requests
                 (i.e. <filename>create-pull-request</filename> and
@@ -330,16 +337,20 @@
                     <listitem><para>
                         Maintain your Metadata in layers that make sense
                         for your situation.
-                        See the "<link linkend='understanding-and-creating-layers'>Understanding
-                        and Creating Layers</link>" section for more information on
-                        layers.
+                        See the
+                        "<ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>"
+                        section in the Yocto Project Overview and Concepts
+                        Manual and the
+                        "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>"
+                        section for more information on layers.
                         </para></listitem>
                     <listitem><para>
                         Separate the project's Metadata and code by using
                         separate Git repositories.
                         See the
                         "<ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
-                        section for information on these repositories.
+                        section in the Yocto Project Overview and Concepts
+                        Manual for information on these repositories.
                         See the
                         "<link linkend='locating-yocto-project-source-files'>Locating Yocto Project Source Files</link>"
                         section for information on how to set up local Git
@@ -360,7 +371,8 @@
                         </para></listitem>
                     <listitem><para>
                         The Yocto Project community encourages you
-                        to send patches to the project to fix bugs or add features.
+                        to send patches to the project to fix bugs or add
+                        features.
                         If you do submit patches, follow the project commit
                         guidelines for writing good commit messages.
                         See the "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
@@ -369,10 +381,12 @@
                     <listitem><para>
                         Send changes to the core sooner than later
                         as others are likely to run into the same issues.
-                        For some guidance on mailing lists to use, see the list in the
+                        For some guidance on mailing lists to use, see the list
+                        in the
                         "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
                         section.
-                        For a description of the available mailing lists, see the
+                        For a description of the available mailing lists, see
+                        the
                         "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
                         section in the Yocto Project Reference Manual.
                         </para></listitem>