aldryn · evildmp · Apr 20, 2015 · Apr 27, 2015
diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst
diff --git a/docs/improving.rst b/docs/improving.rst
@@ -21,10 +21,10 @@ documentation. In fact if you're not an expert, your opinion is especially impor
 Documentation structure
 ***********************
 
-The documentation's structure reflects its three chief functions:
+Our documentation is divided into the following main sections:
 
-* :doc:`introduction/index` to introduce concepts and explain basic aspects of the technology
-* :doc:`how-to/index` to take the user step-by-step through some key processes
+* :doc:`/introduction/index` (``introduction``): step-by-step tutorials to get
+  you up and running
 * :doc:`Reference <reference/index>` to provide in-depth technical reference material
 
 As far as possible when writing documentation it should be aimed at a place in one of these
@@ -63,30 +63,46 @@ We use Python documentation conventions for section marking:
 
 * ``#`` with overline, for parts
 * ``*`` with overline, for chapters
-* ``=``, for sections
-* ``-``, for subsections
-* ``^``, for subsubsections
-* ``"``, for paragraphs
+* ``=`` for sections
+* ``-`` for subsections
+* ``^`` for subsubsections
+* ``"`` for paragraphs
 
 Inline markup
 -------------
 
-* use double backticks - ````settings.py```` - for:
-    * literals
-    * filenames
-    * names of fields and other items in the Admin interface:
-* use emphasis - ``*Home*`` for:
-    * the names of available options in the Admin
-    * values in or of fields
-* use strong emphasis - ``**Control Panel**`` for:
-    * buttons that perform an action
-    * the names of key Aldryn components when they are first used in a page or section
+* use backticks - `````` - for:
+    * literals - ````cms.models.pagemodel````
+    * filenames - ``edit ``settings.py````
+    * names of fields and other specific items in the Admin interface - ``edit ``Redirect````
+* 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*``
+* use strong emphasis - ``**`` - around:
+    * buttons that perform an action - ``hit **Save and close**``
+
+Rules for using technical words
+-------------------------------
+
+There should be one consistent way of rendering any technical word, depending on its context.
+Please follow these rules:
+
+* when introducing a key term for the the first time, or for the first time in a document,
+  highlight it to draw attention to it: "**Placeholders** are special model fields"
+* in general use, simply use the word as if it were any ordinary word, with no capitalisation or
+  highlighting: "Your placeholder can now be used." However, use "the Marketplace", "the Network" etc
+* at the start of sentences or titles, capitalise in the usual way: "Placeholder management guide"
+* when the word refers specifically to an object in the code, highlight it as a literal:
+  "``Placeholder`` methods can be overwritten as required" - when appropriate, link the term to
+  further reference documentation as well as simply highlighting it
 
 .. _Sphinx: http://sphinx.pocoo.org/
 .. _restructuredText: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
 
 Internal links
 --------------
 
-Please use absolute link paths - `/packaging` - rather than relative paths - `packaging`. It makes
-it much easier to update them with a search & replace when files are moved.
+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.
diff --git a/docs/index.rst b/docs/index.rst
@@ -16,19 +16,34 @@
 Welcome to Aldryn
 #################
 
-`Aldryn`_ is an easy-to-use and developer-friendly content management platform.
+`Aldryn`_ is a cloud-based platform for Django-based websites.
 
-Aldryn has been designed to meet the needs of:
+At the heart of Aldryn is `django CMS`_, a powerful and extensible open-source web content
+management system, and a large and growing ecosystem of compatible applications.
 
-* **web content creators**, who require an efficient and reliable way to produce content
+Aldryn has been designed to meet the needs of three distinct groups of web professionals.
 
-* **agencies**, who work with multiple clients and content creators, and need to manage them all
 
-* **web developers**, who implement designs and create applications, and need a low-friction
-  workflow for their deployment
+**Content creators**, who require an efficient and reliable way to produce content.
+
+django CMS and the numerous Addons that can be installed make Aldryn a powerful content creation
+platform. A number of Addons already exist in the Aldryn Marketplace, while developers can readily
+develop and deploy their own, from new or existing Django packages.
+
+**Web agencies and designers**, who work with multiple clients and content creators, and need to manage them all.
+
+Typically they need to provide their clients with a site that the client can subsequently manage on
+their own. Aldryn provides flexible and effective ways of setting up sites so that an agency can
+then hand the, over to clients, while still being able to retain oversight if necessary. Future - or
+indeed continuous - development is possible, because Aldryn has been designed to be a platform as
+much for hosting and site management as for development.
+
+**Web application developers**, who implement designs and create applications, and need a
+low-friction workflow for their deployment.
+
+Aldryn provides a fully-featured Django environment that can easily be recreated locally for
+development.
 
-At the heart of Aldryn is `django CMS`_, a powerful and extensible open-source web content
-management system, and a large - and growing - ecosystem of compatible applications.
 
 The platform also provides:
 
@@ -75,15 +90,8 @@ Table of Contents
 
     self
     introduction/index
-    how-to/index
-    reference/sites/index
-    reference/client/index
-    reference/addons/index
-    reference/boilerplates/index
-    reference/themes/index
-    reference/workflows_for_agencies/index
+    reference/index
     improving
-    glossary
 
 .. _Aldryn: http://www.aldryn.com/
 .. _django CMS: http://django-cms.org/
diff --git a/docs/how-to/create_site.rst → docs/introduction/create_site.rst b/docs/how-to/create_site.rst → docs/introduction/create_site.rst
diff --git a/docs/how-to/creating_custom_addon.rst → docs/introduction/creating_custom_addon.rst b/docs/how-to/creating_custom_addon.rst → docs/introduction/creating_custom_addon.rst
@@ -1,6 +1,6 @@
-=====================
+#####################
 Create a custom Addon
-=====================
+#####################
 
 In the :doc:`/introduction/index` we got an Aldryn site running in a local environment. If you haven't got to that
 stage yet, you should follow that tutorial first before returning here to continue.
@@ -9,8 +9,9 @@ An Addon must conform to certain standards, but apart from some minor additional
 long as your Addon is well-packaged you should not encounter any difficulty. The good news is that Aldryn even helps
 package it.
 
+*********************************
 Create a simple django CMS plugin
-=================================
+*********************************
 
 For the purposes of this walkthrough, we'll create a basic plugin that greets the logged-in user by name.
 
@@ -68,8 +69,9 @@ Try it out: start the runserver, and add your plugin to a page
 
 .. _package_your_addon:
 
+******************
 Package your Addon
-==================
+******************
 
 Creating packages, especially if you've not done it before, can be tricky and frustrating to get right. The Aldryn
 Control Panel takes much of the hard work out of the process for you, automatically generating several of the files
@@ -91,7 +93,7 @@ your Addon.
 Let's download and look at these files one-by-one.
 
 ``addon.json``
---------------
+==============
 
 The special requirements for Addon packaging are dealt with in an ``addon.json`` file containing information about the
 Addon. They are are in discussed in further detail in :ref:`addon-packaging`, but in brief it contains a dictionary
@@ -106,32 +108,32 @@ know how to use Python's packaging to ensure that they're actually installed alo
 In fact all these files can be edited to meet more complex needs.
 
 ``setup.py``
-------------
+============
 
 An Addon needs to be packaged in the usual Python way, starting with the ``setup.py`` file.
 
 Again, Aldryn provides a minimal but adequate file ready for you to use.
 
 ``MANIFEST.in``
----------------
+===============
 
 The ``MANIFEST.in`` file lists the locations of resources such as templates that need to be included in an installation.
 
 ``LICENSE.txt``
----------------
+===============
 
 A licence file is required. This may not matter very much if you're just using your application on
 your own sites, but if you plan to put it on the Aldryn Marketplace you should think carefully
 about appropriate licence terms.
 
 ``README.rst``
---------------
+==============
 
 Your ``README.rst`` will be empty until you provide a ``Description`` and **Save** the Addon - but of course you can
 edit the README file manually too.
 
 ``__init.py__``
----------------
+===============
 
 Finally, you have an ``__init.py__`` that provides a ``__version__`` (that starts at "0.0.1" by default).
 
@@ -151,8 +153,9 @@ like::
             views.py
             templates
 
+********
 Test it!
-========
+********
 
 The Aldryn client includes a validation tool, that will report on problems it finds in your Addon.
 
@@ -168,8 +171,9 @@ Now check, in your local development environment, that your newly-packaged Addon
     that some of your Addon's components are available to Django not because you've packaged them
     correctly, but simply in virtue of where you have put them while working on them!
 
+***********************
 Add further information
-=======================
+***********************
 
 If your Addon's only for private use, you don't need to add more. If you'd like other people to make use of it, add
 some more information about it. ``Additional information`` is particularly aimed at other developers who may be
@@ -179,8 +183,9 @@ browsing the Aldryn Marketplace.
 ``Publish on django-cms.org`` will mean that it's also listed amongst the `django CMS Addons
 <https://www.django-cms.org/en/add-ons/>`_.
 
+*******
 Upload
-======
+*******
 
 When you're satisfied that all is correct, you're ready to upload your Addon to Aldryn::
 
@@ -191,8 +196,9 @@ Your Addon is now in the Aldryn Marketplace and ready to be installed.
 Once it has been uploaded, you have the option to make your Addon publicly available in its configuration settings,
 from the Control Panel. Note that once made public, an Addon can't be made private again.
 
+******************
 Install and deploy
-==================
+******************
 
 In an Aldryn project Control Panel, install the Addon now as you'd install any other, and deploy your changes. A few
 minutes later, you should be up and running and able to use your application in Aldryn.

diff --git a/docs/introduction/index.rst b/docs/introduction/index.rst
@@ -1,42 +1,18 @@
-############
-Introduction
-############
+.. ATTENTION::
+   This documentation is currently in development. We'd be delighted to have your feedback, or even
+   better, your contributions. If you’d like to help by contributing, fork us on `GitHub
+   <https://github.com/aldryn/aldryn-docs>`_!
 
-Aldryn is a cloud-based platform for Django-based websites.
+#########
+Tutorials
+#########
 
-.. toctree::
-    :maxdepth: 1
-
-    Key concepts <concepts>
-    Key tools <tools>
-
-================
-Aldryn's purpose
-================
-
-Aldryn is designed to meet the needs of three distinct groups of web professionals:
+The aim of the documents in this section is not to provide a comprehensive reference, but to take you through the steps of some of the key processes you'll need to work through while using Aldryn.
 
-* content creators
-* agencies and designers
-* web application developers
 
-In order to meet the multifarious and sometimes competing needs of these three groups, Aldryn
-provides a suite of integrated tools and workflows.
-
-**Content creators** are served by django CMS and the Aldryn Addons that can be installed. A number
-of Addons already exist in the Aldryn Marketplace, but developers can readily develop and deploy
-their own, from new or existing Django packages.
-
-**Web agencies and designers** typically need to provide their clients with a site that the client
-can subsequently manage on their own, working with tools and developers they are experienced with,
-and able to work with rapidly. Aldryn provides flexible and effective ways of setting up sites so
-that an agency can then hand over to clients, while still being able to retain oversight if
-necessary. Future - or indeed continuous - development is possible, because Aldryn has been
-designed to be a platform as much for hosting and site management as for development.
+.. toctree::
+    :maxdepth: 1
 
-For **web application developers**, Aldryn provides a fully-featured Django environment. At the
-same time it is a strongly-opinionated environment, which is of course necessary to permit it to
-function as a cloud-based offering, that can be managed without difficulty by a non-technical user
-using the Control Panel. Aldryn solves the problem of meeting these competing needs by making
-possible **Local Development** in an environment (supported by tools that build it automaticallu)
-that replicates the cloud environment.
+    create_site
+    local_development
+    creating_custom_addon
diff --git a/docs/how-to/local_development.rst → docs/introduction/local_development.rst b/docs/how-to/local_development.rst → docs/introduction/local_development.rst
@@ -1,6 +1,6 @@
-======================================
+######################################
 Aldryn's local development environment
-======================================
+######################################
 
 If your code works with django CMS, you can expect it to work with Aldryn.
 
@@ -17,22 +17,22 @@ replicates as far as possible the one your code will encounter when deployed.
    or even better, your contributions </improving>`. This documentation is on `GitHub
    <https://github.com/aldryn/aldryn-docs>`_
 
-
+**********************************
 Replicate your Aldryn site locally
-==================================
+**********************************
 
 You'll need the :ref:`Aldryn command-line client <aldryn_client>` installed, and a site - even the
 most basic one will do - that's active on Aldryn.
 
 The Aldryn client
------------------
+=================
 
 The client's available from PyPI::
 
     pip install aldryn-client
 
 Replicate your Aldryn site locally
-----------------------------------
+==================================
 
 Login to your Aldryn account::
 
@@ -56,7 +56,7 @@ created. Within it you'll find:
 * ``dev`` - a directory that Aldryn puts on the Python path for your convenience
 
 Set up the local database
--------------------------
+=========================
 
 You'll need to get a local copy of your Aldryn database running.
 
@@ -72,7 +72,7 @@ Using your local PostgreSQL database client, import the ``database.dump`` file,
 the new database's name and any permissions match those in the local site's settings.
 
 Use local settings
-------------------
+==================
 
 You're going to need to adjust the settings for your local version of the project, so that it can
 use your local database.
@@ -112,7 +112,7 @@ installed in the project on Aldryn)::
         ]
 
 Let's go
---------
+========
 
 You need to activate this new virtualenv, install the requirements and fire up the Django runserver::