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>

1 files changed, 33 insertions, 22 deletions

diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index ad5f3c9ecf..fbb9d5faef 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>.