Move Annotations introduction to the reference.

docs/en/reference/annotations-reference.rst

@@ -1,6 +1,32 @@
 Annotations Reference
 =====================
 
+You've probably used docblock annotations in some form already,
+most likely to provide documentation metadata for a tool like
+``PHPDocumentor`` (@author, @link, ...). Docblock annotations are a
+tool to embed metadata inside the documentation section which can
+then be processed by some tool. Doctrine 2 generalizes the concept
+of docblock annotations so that they can be used for any kind of
+metadata and so that it is easy to define new docblock annotations.
+In order to allow more involved annotation values and to reduce the
+chances of clashes with other docblock annotations, the Doctrine 2
+docblock annotations feature an alternative syntax that is heavily
+inspired by the Annotation syntax introduced in Java 5.
+
+The implementation of these enhanced docblock annotations is
+located in the ``Doctrine\Common\Annotations`` namespace and
+therefore part of the Common package. Doctrine 2 docblock
+annotations support namespaces and nested annotations among other
+things. The Doctrine 2 ORM defines its own set of docblock
+annotations for supplying object-relational mapping metadata.
+
+.. note::
+
+    If you're not comfortable with the concept of docblock
+    annotations, don't worry, as mentioned earlier Doctrine 2 provides
+    XML and YAML alternatives and you could easily implement your own
+    favourite mechanism for defining ORM metadata.
+
 In this chapter a reference of every Doctrine 2 Annotation is given
 with short explanations on their context and usage.
 

docs/en/reference/basic-mapping.rst

@@ -1,10 +1,24 @@
 Basic Mapping
 =============
 
-This chapter explains the basic mapping of objects and properties.
+This guide explains the basic mapping of entities and properties.
+After working through this guide you should know:
+
+- How to create PHP classes that can be saved in the database with Doctrine
+- How to configure the mapping between columns on tables and properties on
+  entities. 
+- Defining primary keys and how identifiers are generated by Doctrine
+- What Doctrine types are
+
 Mapping of associations will be covered in the next chapter on
 :doc:`Association Mapping <association-mapping>`.
 
+Guide Assumptions
+-----------------
+
+You should have already :doc:`installed and configure <configuration>`
+Doctrine.
+
 Mapping Drivers
 ---------------
 
@@ -33,36 +47,6 @@ that explain them in more detail. There is also a reference chapter for
     cache (not recommended!) then the XML driver is the fastest by using PHP's
     native XML support.
 
-Introduction to Docblock Annotations
-------------------------------------
-
-You've probably used docblock annotations in some form already,
-most likely to provide documentation metadata for a tool like
-``PHPDocumentor`` (@author, @link, ...). Docblock annotations are a
-tool to embed metadata inside the documentation section which can
-then be processed by some tool. Doctrine 2 generalizes the concept
-of docblock annotations so that they can be used for any kind of
-metadata and so that it is easy to define new docblock annotations.
-In order to allow more involved annotation values and to reduce the
-chances of clashes with other docblock annotations, the Doctrine 2
-docblock annotations feature an alternative syntax that is heavily
-inspired by the Annotation syntax introduced in Java 5.
-
-The implementation of these enhanced docblock annotations is
-located in the ``Doctrine\Common\Annotations`` namespace and
-therefore part of the Common package. Doctrine 2 docblock
-annotations support namespaces and nested annotations among other
-things. The Doctrine 2 ORM defines its own set of docblock
-annotations for supplying object-relational mapping metadata.
-
-.. note::
-
-    If you're not comfortable with the concept of docblock
-    annotations, don't worry, as mentioned earlier Doctrine 2 provides
-    XML and YAML alternatives and you could easily implement your own
-    favourite mechanism for defining ORM metadata.
-
-
 Persistent classes
 ------------------