diff --git a/docs/en/cookbook/choosing-phpcr-implementation.rst b/docs/en/cookbook/choosing-phpcr-implementation.rst
new file mode 100644
index 000000000..c61d05c91
--- /dev/null
+++ b/docs/en/cookbook/choosing-phpcr-implementation.rst
@@ -0,0 +1,40 @@
+.. index::
+ single: PHPCR Implementations
+
+Choosing a PHPCR Implementation
+===============================
+
+To use PHPCR-ODM, you need to decide on the PHPCR implementation you want to
+use. The implementation is a special kind of database that is responsible for
+storing all the content you want to persist. While every content repository
+can have very different requirements and performance characteristics, the API
+is the same for all of them.
+
+Furthermore, since the API defines an export/import format, you can always
+switch to a different content repository implementation later on.
+
+.. tip::
+
+ If you are just getting started with the CMF, it is best to choose a
+ content repository based on a storage engine that you are already familiar
+ with. For example, **Jackalope with Doctrine DBAL** will work with your
+ existing RDBMS and does not require you to install Java Once you have a
+ working application it should be easy to switch to another option.
+
+Jackalope with Jackrabbit
+-------------------------
+
+The most feature complete and performant implementation available today.
+Jackrabbit can persist into the file system, a database and other storage
+layers.
+
+The main drawback is that Jackrabbit requires the Java runtime.
+
+See :doc:`running-jackrabbit` for instructions how to install and run jackrabbit.
+
+Jackalope with Doctrine DBAL
+----------------------------
+
+A solid and tested implementation that is fine for small to medium sized
+projects. It can run on just a relational database (currently tested with
+MySQL, PostgreSQL and SQLite).
diff --git a/docs/en/cookbook/running-jackrabbit.rst b/docs/en/cookbook/running-jackrabbit.rst
new file mode 100644
index 000000000..e74237c0c
--- /dev/null
+++ b/docs/en/cookbook/running-jackrabbit.rst
@@ -0,0 +1,36 @@
+.. index::
+ single: Jackrabbit
+
+Running Jackrabbit
+==================
+
+`Apache Jackrabbit`_ is the reference implementation for the Java Content
+Repository (JCR) standard. `jackalope-jackrabbit`_ implements PHPCR on top
+of the Jackrabbit remoting capabilities.
+
+Get the latest Apache Jackrabbit version from the project's
+`official download page`_. Place it in a folder where you want it
+to create the repository fields and start is with:
+
+.. code-block:: bash
+
+ $ java -jar jackrabbit-standalone-*.jar
+
+By default the server is listening on the 8080 port, you can change this
+by specifying the port on the command line:
+
+.. code-block:: bash
+
+ $ java -jar jackrabbit-standalone-*.jar --port 8888
+
+For unix systems, you can get the start-stop script for ``/etc/init.d``
+`here`_.
+
+More information about `running a Jackrabbit server`_ can be found on the
+Jackalope wiki.
+
+.. _`Apache Jackrabbit`: http://jackrabbit.apache.org/jcr/index.html
+.. _`jackalope-jackrabbit`: https://github.com/jackalope/jackalope-jackrabbit
+.. _`official download page`: http://jackrabbit.apache.org/jcr/downloads.html
+.. _`here`: https://github.com/sixty-nine/Jackrabbit-startup-script
+.. _`running a Jackrabbit server`: https://github.com/jackalope/jackalope/wiki/Running-a-jackrabbit-server
diff --git a/docs/en/index.rst b/docs/en/index.rst
index 60d8d1afb..a7341d222 100644
--- a/docs/en/index.rst
+++ b/docs/en/index.rst
@@ -77,14 +77,11 @@ Cookbook
--------
* **Tricks**:
+ :doc:`Chosing a PHPCR implementation <cookbook/choosing-phpcr-implementation>` |
+ :doc:`Running Jackrabbit <cookbook/running-jackrabbit>` |
:doc:`Last modification timestamp <cookbook/last-modified>` |
:doc:`Custom Document Class Mapper <cookbook/custom_documentclass_mapper>` |
:doc:`Convert documents between translated and untranslated <cookbook/refactoring-multilang>`
-.. TODO: write these
- |
- :doc:`Blending ORM and PHPCR-ODM <cookbook/blending-orm-and-phpcr-odm>` |
- :doc:`Mapping classes to ORM and PHPCR-ODM <cookbook/mapping-classes-to-orm-and-phpcr-odm>` |
-
-Also have a look at the `Doctrine ORM cookbook <http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/#cookbook>`_,
+Also have a look at the `Doctrine ORM cookbook <https://www.doctrine-project.org/projects/doctrine-orm/en/latest/#cookbook>`_,
notably the entries in the *Implementation* section apply to PHPCR-ODM as well.
diff --git a/docs/en/reference/introduction.rst b/docs/en/reference/introduction.rst
index cc70ea9ad..d5618f2e1 100644
--- a/docs/en/reference/introduction.rst
+++ b/docs/en/reference/introduction.rst
@@ -27,9 +27,7 @@ abstract base class or interface. A document class must not be final
or contain final methods. Additionally it must not implement
**clone** nor **wakeup**.
-.. todo: or :doc:`do so safely <../cookbook/implementing-wakeup-or-clone>`.
-
-See the :doc:`architecture chapter <../reference/architecture>` for a full list of the restrictions
+See the :doc:`architecture chapter <architecture>` for a full list of the restrictions
that your entities need to comply with.
A document contains persistable properties. A persistable property
@@ -54,29 +52,13 @@ We do not build a web interface but simple run scripts on the command line to ke
Setup Project
-------------
-Create a file composer.json in your project directory.
-
-.. code-block:: javascript
-
- {
- "minimum-stability": "dev",
- "require": {
- "doctrine/phpcr-odm": "~1.2",
- "jackalope/jackalope-doctrine-dbal": "~1.1"
- },
- "autoload": {
- "psr-0": { "Demo\\": "src/" }
- }
- }
-
-Then run the following commands on your command line
+Use composer to install PHPCR-ODM and a PHPCR implementation:
.. code-block:: bash
- $ curl -s http://getcomposer.org/installer | php --
- $ php composer.phar install
+ composer require doctrine/phpcr-odm jackalope/jackalope-doctrine-dbal
-This will download the dependencies into the vendor/ folder and generate ``vendor/autoload.php``.
+See :doc:`../cookbook/choosing-phpcr-implementation` for alternatives to the Jackalope Doctrine-DBAL implementation.
.. _intro-bootstrap: