documentation/dev-manual: Incorporated Joshua Lock's review comments.

(From yocto-docs rev: d4bf6343d7575ff96030242e2025570db52b515b)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

3 files changed, 52 insertions, 37 deletions

diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index c6662d3..2dfc46e 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -170,8 +170,8 @@
         </para>
 
         <para>
-            You can view a video presentation of the BSP creation process 
-            <ulink url='http://free-electrons.com/blog/elc-2011-videos'>here</ulink>.  
+            You can view a video presentation on "Building Custom Embedded Images with Yocto"
+            at <ulink url='http://free-electrons.com/blog/elc-2011-videos'>Free Electrons</ulink>.  
             You can also find supplemental information in the 
             <ulink url='http://yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html'>
             Board Support Package (BSP) Development Guide</ulink>.
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index ad5f3c9..fbb9d5f 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -82,7 +82,7 @@
     <para>
         For any supported release of Yocto Project you can go to the Yocto Project website’s 
         <ulink url='http://www.yoctoproject.org/download'>download page</ulink> and get a 
-        <filename>.bz2</filename> tarball of the release.  
+        tarball of the release.  
         You can also go to this site to download any supported BSP tarballs.
         Unpacking the tarball gives you a hierarchical directory structure of Yocto Project 
         files that lets you develop using the Yocto Project.
@@ -133,50 +133,57 @@
         Some terms are universal but are included here just in case:
     <itemizedlist>
         <listitem><para><emphasis>Image</emphasis> - An image is a collection of recipes created
-            with BitBake (baked) and made part of a root filesystem.</para></listitem>
+            with BitBake (baked) and made part of a root filesystem.
+            Images are both the binary output that runs on specific hardware and for specific
+            use cases as well as a metadata recipe that BitBake processes to generate the 
+            binary output.</para></listitem>
         <listitem><para><emphasis>Recipe</emphasis> - A set of instructions for building packages.  
             A recipe describes where you get source code and which patches to apply.
             Recipes describe dependencies for libraries or for other recipes and they 
             also contain configuration and compilation options.  
-            Recipes also let you customize how software is installed into images.  
-            Recipes contain the logical unit of execution, the software/images to build and 
+            Recipes contain the logical unit of execution, the software/images to build, and 
             use the <filename>.bb</filename> file extension.</para></listitem>
         <listitem><para><emphasis>BitBake</emphasis> - The task executor and scheduler used by Yocto Project
             to build images. 
             For more information on BitBake, see the <ulink url='http://bitbake.berlios.de/manual/'>
             BitBake documentation</ulink>.</para></listitem>
-        <listitem><para><emphasis>Package</emphasis> - The output from a baked recipe.
+        <listitem><para><emphasis>Package</emphasis> - The packaged output from a baked recipe.
             A package is generally the compiled binaries produced from the recipe's sources.  
             You ‘bake’ something by running it through BitBake.</para></listitem>
-        <listitem><para><emphasis>Layer</emphasis> - A logical collection of recipes representing the core, 
+        <listitem><para><emphasis>Layer</emphasis> - A collection of recipes representing the core, 
             a BSP, or an application stack.</para></listitem>
-        <listitem><para><emphasis>Metadata</emphasis> - Information for a build that is generally 
-            architecture-independent.  
-            This information includes Task definitions in recipes, classes, and configuration 
-            information.</para></listitem>
+        <listitem><para><emphasis>Metadata</emphasis> - A term used throughout the Yocto Project 
+            documentation that refers to the files that BitBake parses when building an image. 
+            Metadata includes recipes, classes, and configuration files.</para></listitem>
         <listitem><para><emphasis>Configuration File</emphasis>:  Configuration information in the 
             <filename>.conf</filename> files provides global definitions of variables.  
-            The <filename>build/conf/local.conf</filename> configuration file defines local user-defined variables.  
+            The <filename>build/conf/local.conf</filename> configuration file defines user-defined variables
+            that effect each build.  
             The <filename>distro/poky.conf</filename> configuration file defines Yocto ‘distro’ configuration 
-            variables.  
-            The <filename>machine/beagleboard.conf</filename> configuration file defines machine-specific variables
-            (i.e. Texas Instruments ARM Cortex-A8 development board in this example.  
+            variables used only when building with this policy.  
+            The <filename>machine/beagleboard.conf</filename> configuration file defines variables
+            for the Beagleboard and are only used when building for that target 
+            (i.e. Texas Instruments ARM Cortex-A8 development board).  
             Configuration files end with a <filename>.conf</filename> filename extension.</para></listitem>
-        <listitem><para><emphasis>Classes</emphasis> - Files that encapsulate and inherit logic.  
+        <listitem><para><emphasis>Classes</emphasis> - Files that provide for logic encapsulation
+            and inheritance allowing commonly used pattrerns to be defined once and easily used 
+            in multiple recipes.  
             Class files end with the <filename>.bbclass</filename> filename extension.</para></listitem>
         <listitem><para><emphasis>Append Files</emphasis> - Files that append build information to 
             a recipe file.  
             Information in append files override the information in the similarly-named recipe file.
             Append files use the <filename>.bbappend</filename> filename suffix.</para></listitem>
-        <listitem><para><emphasis>Tasks</emphasis> - Arbitrary groups of software used to contain Recipes.  
-            You simply use Tasks to hold recipes that when build usually accomplished a single task.  
+        <listitem><para><emphasis>Tasks</emphasis> - Arbitrary groups of software Recipes.  
+            You simply use Tasks to hold recipes that when built usually accomplish a single task.  
             For example, a task could contain the recipes for a company’s proprietary or value-add software.  
             Or the task could contain the recipes that enable graphics. 
             A task is really just another recipe.  
             Because task files are recipes, they end with the <filename>.bb</filename> filename 
             extension.</para></listitem>
         <listitem><para><emphasis>OE-Core</emphasis> - A core set of metadata originating 
-            with OpenEmbedded (OE) that is shared between OE and the Yocto Project.</para></listitem>
+            with OpenEmbedded (OE) that is shared between OE and the Yocto Project.
+            This metadata is found in the <filename>meta</filename> directory of the Yocto Project
+            files.</para></listitem>
         <listitem><para><emphasis>Upstream</emphasis> - A reference to source code or repositories
             that are not local to the development system but located in a master area that is controlled
             by the maintainer of the source code.
@@ -223,7 +230,9 @@
         <filename>&lt;build_directory&gt;/tmp/deploy/images/licenses</filename>.  
         If a module requires a license that is not in the base list, the build process 
         generates a warning during the build.  
-        It is up to the developer to resolve potential licensing issues.
+        These tools make it easier for a developer to be certain of the licenses with which
+        their shipped products must comply.
+        However, it is still up to the developer to resolve potential licensing issues.
     </para>
 
     <para>
@@ -470,8 +479,10 @@
     </para>
 
     <para>
-        Sometimes it is helpful to submit, investigate, or track a bug against the Yocto Project itself.  
-        While normally this is a process relevant only to Yocto Project developers, you can find information 
+        Sometimes it is helpful to submit, investigate, or track a bug against the Yocto Project itself
+        such as when discovering an issue with some component of the build system that acts contrary 
+        to the documentation or expectations.  
+        You can find information 
         for Bugzilla configuration and bug tracking procedures specific to the Yocto Project 
         <ulink url='https://wiki.yoctoproject.org/wiki/Bugzilla_Configuration_and_Bug_Tracking'>here</ulink>.     
     </para>
@@ -487,7 +498,7 @@
         Here are some things to remember when dealing with bugs against the Yocto Project:   
     <itemizedlist>
         <listitem><para>The Yocto Project follows a naming bug-naming convention: 
-            <filename>[YOCTO &lt;number&gt;]</filename>, where <filename>&lt;number&gt;</filename> is the 
+            <filename>[YOCTO #&lt;number&gt;]</filename>, where <filename>&lt;number&gt;</filename> is the 
             assigned defect ID used in Bugzilla.  
             So, for example, a valid way to refer to a defect when creating a commit comment 
             would be <filename>[YOCTO 1011]</filename>.   
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index 48f98b5..07caed3 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -24,15 +24,16 @@
 
     <para>
         The Yocto Project is an open-source collaboration project focused on embedded Linux development.  
-        The project provides a recent Linux kernel along with a set of system commands, libraries, 
-        and system components suitable for the embedded developer.  
-        The Yocto Project also features the Sato reference User Interface should you be dealing with 
-        devices with restricted screens.
+        The project currently provides a build system and various ancillary tools suitable for the 
+        embedded developer.  
+        The Yocto Project also features the Sato reference User Interface, which is optimized for 
+        stylus driven, low-resolution screens.
     </para>
 
     <para>
         You can use the Yocto Project, which uses the BitBake build tool, to develop complete Linux 
-        images and user-space applications for architectures based on ARM, MIPS, PowerPC, x86 and x86-64.  
+        images and associated user-space applications for architectures based on ARM, MIPS, PowerPC, 
+        x86 and x86-64.  
         You can perform target-level testing and debugging as well as test in a hardware emulated environment.  
         And, if you are an Eclipse user, you can install an Eclipse Yocto Plug-in to allow you to 
         develop within that familiar environment.
@@ -45,16 +46,18 @@
     <para>
         Here is what you need to get set up to use the Yocto Project:
         <itemizedlist>
-            <listitem><para><emphasis>Host System:</emphasis>  You need a recent release of Fedora, 
-                OpenSUSE, Debian, or Ubuntu.  
-                You should have a reasonably current Linux-based host system.  
+            <listitem><para><emphasis>Host System:</emphasis>  You should have a reasonably current 
+                Linux-based host system.
+                You will have the best results with a recent release of Fedora, 
+                OpenSUSE, or Ubuntu as these releases are frequently tested and officially supported 
+                host systems.  
                 You should also have about 100 gigabytes of free disk space for building images.
                 </para></listitem>
             <listitem><para><emphasis>Packages:</emphasis>  The Yocto Project requires certain packages
-                exist on your development system.  
-                See the <ulink url='http://www.yoctoproject.org/docs/yocto-quick-start/yocto-project-qs.html#packages'>
+                exist on your development system (e.g. Python 2.6 or 2.7).  
+                See <ulink url='http://www.yoctoproject.org/docs/yocto-quick-start/yocto-project-qs.html#packages'>
                 The Packages</ulink> section in the Yocto Project Quick start for the exact package 
-                requirements.</para></listitem>
+                requirements and the installation commands for the supported distributions.</para></listitem>
             <listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis>  
                 You need a release of the Yocto Project.  
                 You can get set up with local Yocto Project files one of two ways depending on whether you 
@@ -210,7 +213,8 @@
                         wiki page</ulink> referenced earlier covers how to 
                         set up the <filename>meta-intel</filename> Git repository.</para></listitem>
                 </itemizedlist></para></listitem>
-            <listitem><para><emphasis>Eclipse Yocto Plug-in:</emphasis>  If you are developing using the 
+            <listitem><para><emphasis>Eclipse Yocto Plug-in:</emphasis>  If you are developing 
+                applications using the 
                 Eclipse Integrated Development Environment (IDE) you will need this plug-in.  
                 See the 
                 <ulink url='http://www.yoctoproject.org/docs/adt-manual/adt-manual.html#setting-up-the-eclipse-ide'>
@@ -237,7 +241,7 @@
                 previous section.</para></listitem>
             <listitem><para>Initialize the build environment by sourcing a build environment 
                 script.</para></listitem>
-            <listitem><para>Make sure the <filename>conf/local.conf</filename> configuration file is set 
+            <listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file is set 
                 up how you want it.  
                 This file defines the target machine architecture and and other build options.</para></listitem>
             <listitem><para>Build the image using the BitBake command.