Updated readme and contribution docs

README.rst

@@ -72,14 +72,14 @@ http://docs.django-cms.org/en/latest/introduction/index.html
 Quick Start
 ***********
 
-You can use the `django CMS installer <https://github.com/nephila/djangocms-installer>`_::
+You can use the `django CMS installer <http://djangocms-installer.readthedocs.org>`_::
 
     $ pip install --upgrade virtualenv
     $ virtualenv env
     $ source env/bin/activate
     (env) $ pip install djangocms-installer
     (env) $ mkdir myproject && cd myproject
-    (env) $ djangocms -p . my_demo
+    (env) $ djangocms -p -f . my_demo
     (env) $ python manage.py
 
 

docs/contributing/contributing.rst

@@ -142,12 +142,12 @@ your prose can be improved later if necessary.
 Documentation should be:
 
 - written using valid `Sphinx`_/`restructuredText`_ syntax (see below for
-  specifics) and the file extension should be ``.rst``
-- written in English (we have standardised on British spellings)
+  specifics); the file extension should be ``.rst``
+- wrapped at 100 characters per line
+- written in English, using British English spelling and punctuation
 - accessible - you should assume the reader to be moderately familiar with
   Python and Django, but not anything else. Link to documentation of libraries
   you use, for example, even if they are "obvious" to you
-- wrapped at 100 characters per line
 
 Merging documentation is pretty fast and painless.
 
@@ -177,17 +177,17 @@ Documentation structure
 
 Our documentation is divided into the following main sections:
 
-* :doc:`/introduction/index` (``introduction``): step-by-step tutorials to get
+* :doc:`/introduction/index` (``introduction``): step-by-step, beginning-to-end tutorials to get
   you up and running
-* :doc:`/how_to/index` (``how_to``): guides covering more advanced development
+* :doc:`/how_to/index` (``how_to``): step-by-step guides covering more advanced development
 * :doc:`/topics/index` (``topics``): explanations of key parts of the system
 * :doc:`/reference/index` (``reference``): technical reference for APIs, key
   models
   and so on
 * :doc:`/contributing/index` (``contributing``)
 * :doc:`/upgrade/index` (``upgrade``)
-* (in progress Using django CMS (``user``): guides for *using* rather than
-  setting up or developing for the CMS
+* :doc:`/user/index` (``user``): guides for *using* rather than setting up or developing for the
+  CMS
 
 
 Documentation markup
@@ -196,28 +196,61 @@ Documentation markup
 Sections
 --------
 
-We use Python documentation conventions for section marking:
+We mostly follow the Python documentation conventions for section marking::
+
+    ##########
+    Page title
+    ##########
+
+    *******
+    heading
+    *******
+
+    sub-heading
+    ===========
+
+    sub-sub-heading
+    ---------------
+
+    sub-sub-sub-heading
+    ^^^^^^^^^^^^^^^^^^^
 
-* ``#`` with overline, for parts
-* ``*`` with overline, for chapters
-* ``=`` for sections
-* ``-`` for subsections
-* ``^`` for subsubsections
-* ``"`` for paragraphs
+    sub-sub-sub-sub-heading
+    """""""""""""""""""""""
 
 Inline markup
 -------------
 
 * use backticks - `````` - for:
-    * literals - ````cms.models.pagemodel````
-    * filenames - ``edit ``settings.py````
-    * names of fields and other specific items in the Admin interface - ``edit ``Redirect````
+    * literals::
+
+        The ``cms.models.pagemodel`` contains several important methods.
+
+    * filenames::
+
+        Before you start, edit ``settings.py``.
+
+    * names of fields and other specific items in the Admin interface::
+
+        Edit the ``Redirect`` field.
+
 * use emphasis - ``*Home*`` - around:
-    * the names of available options in or parts of the Admin - ``the *Toolbar*``
-    * the names of important modes or states - ``switch to *Edit mode*``
-    * values in or of fields - ``enter *Home*``
+    * the names of available options in or parts of the Admin::
+
+        To hide and show the *Toolbar*, use the...
+
+    * the names of important modes or states::
+
+        ... in order to switch to *Edit mode*.
+
+    * values in or of fields::
+
+        Enter *Home* in the field.
+
 * use strong emphasis - ``**`` - around:
-    * buttons that perform an action - ``hit **Save as draft**``
+    * buttons that perform an action::
+
+        Hit **Save as draft**.
 
 Rules for using technical words
 -------------------------------
@@ -237,6 +270,17 @@ Please follow these rules:
 References
 ----------
 
+Create::
+
+    .. _testing:
+
+and use::
+
+     :ref:`testing`
+
+internal cross-references liberally.
+
+
 Use absolute links to other documentation pages - ``:doc:`/how_to/toolbar``` -
 rather than relative links - ``:doc:`/../toolbar```. This makes it easier to
 run search-and-replaces when items are moved in the structure.

docs/contributing/management.rst

@@ -160,7 +160,7 @@ parts of the CMS - so do the best you can with them.
 Other labels
 ============
 
-:term:`backport`, :term:`blocker`, :term:`has patch` or :term:`easy pickings` labels should be applied as appropriate, to healthy (blue) tickets only/
+:term:`backport`, :term:`blocker`, :term:`has patch` or :term:`easy pickings` labels should be applied as appropriate, to healthy (blue) tickets only.
 
 Comments
 ========
@@ -188,7 +188,7 @@ Every issue should have a status, and be given one as soon as possible. **An iss
 one status applied to it**.
 
 Many of these statuses apply equally well to both issues and pull requests, but some make sense
-only for one or the other
+only for one or the other:
 
 .. glossary::