From 2f7ab001e209fa54260bbc1dd008b9fa0e17baad Mon Sep 17 00:00:00 2001
From: J Bradshaw <jbradsha@users.noreply.github.com>
Date: Sat, 23 May 2015 20:28:22 +0100
Subject: [PATCH] [IMP] doc: grammar and readability

Backport of most of #6827 by J Bradshaw with additional
modifications (and some reverts) during review.

closes #6827
---
 doc/README.rst                 |  77 ------------------------
 doc/api_integration.rst        |  33 +++++------
 doc/cla/individual/jbradsha.md |  11 ++++
 doc/howtos/web.rst             |  83 +++++++++++++-------------
 doc/howtos/website.rst         |  26 ++++-----
 doc/reference/async.rst        |   4 +-
 doc/reference/guidelines.rst   | 103 ++++++++++++++++++---------------
 doc/reference/module.rst       |   8 +--
 doc/reference/security.rst     |   6 +-
 doc/reference/translations.rst |   8 +--
 doc/reference/views.rst        |   8 +--
 doc/reference/workflows.rst    |   2 +-
 doc/setup/deploy.rst           |   8 +--
 13 files changed, 158 insertions(+), 219 deletions(-)
 delete mode 100644 doc/README.rst
 create mode 100644 doc/cla/individual/jbradsha.md

diff --git a/doc/README.rst b/doc/README.rst
deleted file mode 100644
index 883730b84f3..00000000000
--- a/doc/README.rst
+++ /dev/null
@@ -1,77 +0,0 @@
-:orphan:
-
-==================
-Odoo Documentation
-==================
-
-Odoo Theme
-==========
-
-The Odoo Documentation theme is a bootstrap-based mix of http://odoo.com and
-http://getbootstrap.com with additional changes and additions, bundled as
-a Sphinx theme.
-
-The main style file is ``_themes/odoodoc/static/style.less``, it is not
-converted on the fly and must be compiled manually when altere, using the
-official node-based lessc_ tool.
-
-``odoodoc`` must be added as an extension to a project using the theme, it
-fixes some discrepancies between bootstrap_ and Sphinx_ and adds a few
-features:
-
-Sphinx Customizations
----------------------
-
-* toctree bullet lists (HTML ``<ul>``) are given the ``nav`` class
-* the main navigation bar also gets the ``navbar-nav`` and ``navbar-right``
-  set on its root (``navbar-right`` could probably be handled in CSS to avoid
-  having it in the markup)
-* tables are given the ``table`` class
-* colspecs are removed from tables, tables should autolayout
-* ``data-`` attributes are copied straight from the docutils node to the
-  output HTML node
-* an ``odoo`` pygments style based on the bootstrap_ documentation's
-* the normal Sphinx sidebars are suppressed and a new sidebar is injected in
-  ``div.document`` (``sidebar1`` is outside in the base Sphinx layout)
-* HTML5 doctype
-
-Additional features
--------------------
-
-* versions switcher, uses the ``canonical_root`` setting and an additional
-  ``versions`` setting which should be a comma-separated list of available
-  versions. Appends the each version and page name to the root, and displays
-  a list of those links on the current page
-* canonical urls, requires a ``canonical_root`` setting value, and optionally
-  a ``canonical_branch`` (default: ``master``)
-* :guilabel:`Edit on github` link in Sphinx pages if ``github_user`` and
-  ``github_project`` are provided
-* :guilabel:`[source]` links in autodoc content links to github with the same
-  requirements (requires Sphinx 1.2)
-* ``aphorism`` class for admonitions, makes the first line of the admonition
-  inline and the same size as the admonition category (mostly for short,
-  single-phrase admonitions)
-* ``exercise`` directive, mostly for training-type documents, the
-  ``solutions`` tag_ can be used to conditionally show e.g. solutions
-* a number of straight-to-HTML directives:
-
-  ``h:div``
-    a straight div, can be used instead of ``container`` (which adds the
-    ``container`` class to the div it generates, that's really not compatible
-    with Bootstrap_)
-  ``h:address``
-    generates an ``<address>`` node
-  a bunch of roles straight to HTML inline
-    ``mark``, ``insert``, ``delete``, ``strikethrough``, ``small`, ``kbd`` and
-    ``var`` generate the corresponding HTML element
-
-Requirements
-------------
-
-* Sphinx 1.1, 1.2 for code Python code links
-* sphinx-patchqueue (for the content, not the theme)
-
-.. _lessc: http://lesscss.org/#using-less
-.. _bootstrap: http://getbootstrap.com
-.. _sphinx: http://sphinx-doc.org
-.. _tag: http://sphinx-doc.org/markup/misc.html#including-content-based-on-tags
diff --git a/doc/api_integration.rst b/doc/api_integration.rst
index 49bcc60ced6..b41fd1990e0 100644
--- a/doc/api_integration.rst
+++ b/doc/api_integration.rst
@@ -8,8 +8,8 @@
 Web Service API
 ===============
 
-Odoo is mostly extended internally via modules, but much of its features and
-all of its data is also available from the outside for external analysis or
+Odoo is usually extended internally via modules, but many of its features and
+all of its data are also available from the outside for external analysis or
 integration with various tools. Part of the :ref:`reference/orm/model` API is
 easily available over XML-RPC_ and accessible from a variety of languages.
 
@@ -196,8 +196,8 @@ database:
 Logging in
 ----------
 
-Odoo requires users of the API to be authenticated before being able to query
-much data.
+Odoo requires users of the API to be authenticated before they can query most 
+data.
 
 The ``xmlrpc/2/common`` endpoint provides meta-calls which don't require
 authentication, such as the authentication itself or fetching version
@@ -384,7 +384,7 @@ companies for instance:
 Pagination
 ''''''''''
 
-By default a research will return the ids of all records matching the
+By default a search will return the ids of all records matching the
 condition, which may be a huge number. ``offset`` and ``limit`` parameters are
 available to only retrieve a subset of all matched records.
 
@@ -432,8 +432,8 @@ available to only retrieve a subset of all matched records.
 Count records
 -------------
 
-Rather than retrieve a possibly gigantic list of records and count them
-afterwards, :meth:`~openerp.models.Model.search_count` can be used to retrieve
+Rather than retrieve a possibly gigantic list of records and count them,
+:meth:`~openerp.models.Model.search_count` can be used to retrieve
 only the number of records matching the query. It takes the same
 :ref:`domain <reference/orm/domains>` filter as
 :meth:`~openerp.models.Model.search` and no other parameter.
@@ -600,8 +600,7 @@ Listing record fields
 :meth:`~openerp.models.Model.fields_get` can be used to inspect
 a model's fields and check which ones seem to be of interest.
 
-Because
-it returns a great amount of meta-information (it is also used by client
+Because it returns a large amount of meta-information (it is also used by client
 programs) it should be filtered before printing, the most interesting items
 for a human user are ``string`` (the field's label), ``help`` (a help text if
 available) and ``type`` (to know which values to expect, or to send when
@@ -682,7 +681,7 @@ updating a record):
 Search and read
 ---------------
 
-Because that is a very common task, Odoo provides a
+Because it is a very common task, Odoo provides a
 :meth:`~openerp.models.Model.search_read` shortcut which as its name notes is
 equivalent to a :meth:`~openerp.models.Model.search` followed by a
 :meth:`~openerp.models.Model.read`, but avoids having to perform two requests
@@ -690,7 +689,7 @@ and keep ids around.
 
 Its arguments are similar to :meth:`~openerp.models.Model.search`'s, but it
 can also take a list of ``fields`` (like :meth:`~openerp.models.Model.read`,
-if that list is not provided it'll fetch all fields of matched records):
+if that list is not provided it will fetch all fields of matched records):
 
 .. container:: doc-aside
 
@@ -888,8 +887,8 @@ a record).
 Delete records
 --------------
 
-Records can be deleted in bulk by providing the ids of all records to remove
-to :meth:`~openerp.models.Model.unlink`.
+Records can be deleted in bulk by providing their ids to 
+:meth:`~openerp.models.Model.unlink`.
 
 .. container:: doc-aside
 
@@ -945,7 +944,7 @@ Inspection and introspection
           isn't exactly fun in RPC.
 
 While we previously used :meth:`~openerp.models.Model.fields_get` to query a
-model's and have been using an arbitrary model from the start, Odoo stores
+model and have been using an arbitrary model from the start, Odoo stores
 most model metadata inside a few meta-models which allow both querying the
 system and altering models and fields (with some limitations) on the fly over
 XML-RPC.
@@ -955,7 +954,7 @@ XML-RPC.
 ``ir.model``
 ''''''''''''
 
-Provides informations about Odoo models themselves via its various fields
+Provides information about Odoo models via its various fields
 
 ``name``
     a human-readable description of the model
@@ -1100,7 +1099,7 @@ Provides informations about Odoo models themselves via its various fields
 ``ir.model.fields``
 '''''''''''''''''''
 
-Provides informations about the fields of Odoo models and allows adding
+Provides information about the fields of Odoo models and allows adding
 custom fields without using Python code
 
 ``model_id``
@@ -1285,7 +1284,7 @@ the workflow instance associated with the record.
 
 .. container:: doc-aside
 
-    .. warning:: requires that the ``account`` module be installed
+    .. warning:: this example needs ``account`` module installed
 
     .. switcher::
 
diff --git a/doc/cla/individual/jbradsha.md b/doc/cla/individual/jbradsha.md
new file mode 100644
index 00000000000..f1e1e929083
--- /dev/null
+++ b/doc/cla/individual/jbradsha.md
@@ -0,0 +1,11 @@
+United Kingdom, 2015-05-22
+
+I hereby agree to the terms of the Odoo Individual Contributor License
+Agreement v1.0.
+
+I declare that I am authorized and able to make this agreement and sign this
+declaration.
+
+Signed,
+
+John Bradshaw - jbradsha@github.com - https://github.com/jbradsha
diff --git a/doc/howtos/web.rst b/doc/howtos/web.rst
index aba3da8ef55..a18d5dea4cd 100644
--- a/doc/howtos/web.rst
+++ b/doc/howtos/web.rst
@@ -148,7 +148,7 @@ In Odoo web, modules are declared as functions set on the global ``openerp``
 variable. The function's name must be the same as the addon (in this case
 ``oepetstore``) so the framework can find it, and automatically initialize it.
 
-When the web client decides to load your module, it'll call the root function
+When the web client loads your module it will call the root function
 and provide two parameters:
 
 * the first parameter is the current instance of the Odoo web client, it gives
@@ -168,7 +168,7 @@ Much as modules, and contrary to most object-oriented languages, javascript
 does not build in *classes*\ [#classes]_ although it provides roughly
 equivalent (if lower-level and more verbose) mechanisms.
 
-For simplicity and developer-friendliness purposes, Odoo web provides a class
+For simplicity and developer-friendliness Odoo web provides a class
 system based on John Resig's `Simple JavaScript Inheritance`_.
 
 New classes are defined by calling the :func:`~openerp.web.Class.extend`
@@ -307,7 +307,7 @@ This line at the end of the file::
         'petstore.homepage', 'instance.oepetstore.HomePage');
 
 registers our basic widget as a client action. Client actions will be
-explained later in the guide, for now this is just what allows our widget to
+explained later, for now this is just what allows our widget to
 be called and displayed when we select the
 :menuselection:`Pet Store --> Pet Store --> Home Page` menu.
 
@@ -335,9 +335,9 @@ section of page they're in charge of (as a jQuery_ object). Widget content
 should be inserted there. By default, :attr:`~openerp.Widget.$el` is an
 empty ``<div>`` element.
 
-A ``<div>`` element is usually invisible for the user if it does not
-have any content (or specific styles giving it a size) which is why nothing
-is displayed on the page when ``HomePage`` is launched.
+A ``<div>`` element is usually invisible to the user if it has no content (or
+without specific styles giving it a size) which is why nothing is displayed
+on the page when ``HomePage`` is launched.
 
 Let's add some content to the widget's root element, using jQuery::
 
@@ -353,10 +353,10 @@ That message will now appear when you open :menuselection:`Pet Store
 .. note::
 
     to refresh the javascript code loaded in Odoo Web, you will need to reload
-    the page. There is no need to restart the Odoo server
+    the page. There is no need to restart the Odoo server.
 
-The ``HomePage`` widget is used by Odoo Web and managed automatically, to
-learn how to use a widget "from scratch" let's create a new one::
+The ``HomePage`` widget is used by Odoo Web and managed automatically.
+To learn how to use a widget "from scratch" let's create a new one::
 
     local.GreetingsWidget = instance.Widget.extend({
         start: function() {
@@ -438,7 +438,7 @@ of another widget, and exist on behalf of it. We call the container the
 *parent*, and the contained widget the *child*.
 
 Due to multiple technical and conceptual reasons, it is necessary for a widget
-to know who is his parent and who are its children.
+to know who is its parent and who are its children.
 
 :func:`~openerp.Widget.getParent`
     can be used to get the parent of a widget::
@@ -508,9 +508,9 @@ manipulating (and adding to) their DOM::
 
     this.$el.append("<div>Hello dear Odoo user!</div>");
 
-This allows generating and displaying any type of content, but tends to
-rapidly get unwieldy when generating significant amounts of DOM (lots of
-duplication, quoting issues, ...)
+This allows generating and displaying any type of content, but gets unwieldy
+when generating significant amounts of DOM (lots of duplication, quoting
+issues, ...)
 
 As many other environments, Odoo's solution is to use a `template engine`_.
 Odoo's template engine is called :ref:`reference/qweb`.
@@ -578,7 +578,7 @@ the template can be set directly on the widget via its
         },
     });
 
-Although the result look similar, there are two differences between these
+Although the result looks similar, there are two differences between these
 usages:
 
 * with the second version, the template is rendered right before
@@ -916,9 +916,8 @@ Selecting DOM elements within a widget can be performed by calling the
 
     this.$el.find("input.my_input")...
 
-But because it's an extremely common operation, :class:`~openerp.Widget`
-provides an equivalent shortcut through the :func:`~openerp.Widget.$`
-method::
+But because it's a common operation, :class:`~openerp.Widget` provides an
+equivalent shortcut through the :func:`~openerp.Widget.$` method::
 
     local.MyWidget = instance.Widget.extend({
         start: function() {
@@ -1109,7 +1108,7 @@ Exercise
     Then, modify the ``HomePage`` widget to instantiate ``ColorInputWidget``
     and display it. The ``HomePage`` widget should also display an empty
     rectangle. That rectangle must always, at any moment, have the same
-    background color than the color in the ``color`` property of the
+    background color as the color in the ``color`` property of the
     ``ColorInputWidget`` instance.
 
     Use QWeb to generate all HTML.
@@ -1366,11 +1365,10 @@ by the server to translate all the messages of the application. Another one is
 the time zone of the user, used to compute correctly dates and times if Odoo
 is used by people in different countries.
 
-The ``argument`` is necessary in all methods, because if we forget it bad
-things could happen (like the application not being translated
-correctly). That's why, when you call a model's method, you should always give
-it to that argument. The solution to achieve that is to use
-:class:`openerp.web.CompoundContext`.
+The ``argument`` is necessary in all methods, otherwise bad things could
+happen (such as the application not being translated correctly). That's why,
+when you call a model's method, you should always provide that argument. The
+solution to achieve that is to use :class:`openerp.web.CompoundContext`.
 
 :class:`~openerp.web.CompoundContext` is a class used to pass the user's
 context (with language, time zone, etc...) to the server as well as adding new
@@ -1433,7 +1431,7 @@ versus::
   :class:`~openerp.web.Query` for its customization options.
 
 When the query is set up as desired, simply call
-:func:`~openerp.web.Query.all` to perform the actual query and return a
+:func:`~openerp.web.Query.all` to execute it and return a
 deferred to its result. The result is the same as
 :py:meth:`~openerp.models.Model.read`'s, an array of dictionaries where each
 dictionary is a requested record, with each requested field a dictionary key.
@@ -1516,7 +1514,7 @@ Exercises
     ``product.product`` using a special category *Pet Toys*. You can see the
     pre-generated toys and add new ones by going to
     :menuselection:`Pet Store --> Pet Store --> Pet Toys`. You will probably
-    need to explore ``product.product`` in order to create the right domain to
+    need to explore ``product.product`` to create the right domain to
     select just pet toys.
 
     In Odoo, images are generally stored in regular fields encoded as
@@ -1840,10 +1838,10 @@ Views may also want to handle search queries by overriding
 The Form View Fields
 --------------------
 
-A common Odoo web need is the extension of the form view to add new ways of
-displaying form fields.
+A common need is the extension of the web form view to add new ways of
+displaying fields.
 
-All built-in fields have a default display implementation, creating a new
+All built-in fields have a default display implementation, a new
 form widget may be necessary to correctly interact with a new field type
 (e.g. a :term:`GIS` field) or to provide new representations and ways to
 interact with existing field types (e.g. validate
@@ -1871,7 +1869,7 @@ simply use the ``widget`` attribute in the view's XML description:
 Fields are instantiated by the form view after it has read its XML description
 and constructed the corresponding HTML representing that description. After
 that, the form view will communicate with the field objects using some
-methods. Theses methods are defined by the ``FieldInterface``
+methods. These methods are defined by the ``FieldInterface``
 interface. Almost all fields inherit the ``AbstractField`` abstract
 class. That class defines some default mechanisms that need to be implemented
 by most fields.
@@ -1926,13 +1924,13 @@ Creating a New Type of Field
 ''''''''''''''''''''''''''''
 
 In this part we will explain how to create a new type of field. The example
-here will be to re-implement the ``FieldChar`` class and explain progressively
+here will be to re-implement the ``FieldChar`` class and progressively explain
 each part.
 
 Simple Read-Only Field
 """"""""""""""""""""""
 
-Here is a first implementation that will only be able to display a text. The
+Here is a first implementation that will only display text. The
 user will not be able to modify the content of the field.
 
 .. code-block:: javascript
@@ -1972,16 +1970,16 @@ none is specified by the form view (here we assume the default value of a
 Read-Write Field
 """"""""""""""""
 
-Fields that only display their content and don't give the possibility to the
-user to modify it can be useful, but most fields in Odoo allow edition
-too. This makes the field classes more complicated, mostly because fields are
+Read-only fields, which only display content and don't allow the
+user to modify it can be useful, but most fields in Odoo also allow editing.
+This makes the field classes more complicated, mostly because fields are
 supposed to handle both and editable and non-editable mode, those modes are
 often completely different (for design and usability purpose) and the fields
-must be able to switch from one mode to another at any moment.
+must be able to switch between modes at any moment.
 
 To know in which mode the current field should be, the ``AbstractField`` class
 sets a widget property named ``effective_readonly``. The field should watch
-the changes in that widget property and display the correct mode
+for changes in that widget property and display the correct mode
 accordingly. Example::
 
     local.FieldChar2 = instance.web.form.AbstractField.extend({
@@ -2027,17 +2025,16 @@ accordingly. Example::
         </div>
     </t>
 
-In the ``start()`` method (which is called right after a widget has been
+In the ``start()`` method (which is called immediately after a widget has been
 appended to the DOM), we bind on the event ``change:effective_readonly``. That
-will allow use to redisplay the field each time the widget property
+allows us to redisplay the field each time the widget property
 ``effective_readonly`` changes. This event handler will call
 ``display_field()``, which is also called directly in ``start()``. This
 ``display_field()`` was created specifically for this field, it's not a method
-defined in ``AbstractField`` or any other class. This is the method we will
-use to display the content of the field depending we are in read-only mode or
-not.
+defined in ``AbstractField`` or any other class. We can use this method
+to display the content of the field depending on the current mode.
 
-From now on the conception of this field is quite typical, except there is a
+From now on the conception of this field is typical, except there is a
 lot of verifications to know the state of the ``effective_readonly`` property:
 
 * In the QWeb template used to display the content of the widget, it displays
@@ -2243,7 +2240,7 @@ the most useful being:
 
     .. _See the online documentation to know how to use it: http://www.w3schools.com/html/html5_geolocation.asp
 
-    Please also note that it wouldn't be very logical to allow the user to
+    Please also note that the user should not be able to
     click on that button when the form view is in read-only mode. So, this
     custom widget should handle correctly the ``effective_readonly`` property
     just like any field. One way to do this would be to make the button
diff --git a/doc/howtos/website.rst b/doc/howtos/website.rst
index 852897feeaa..1fff9897cc2 100644
--- a/doc/howtos/website.rst
+++ b/doc/howtos/website.rst
@@ -22,7 +22,7 @@ behaviors or by altering existing ones (including behaviors added by other
 modules).
 
 :ref:`Odoo's scaffolding <reference/cmdline/scaffold>` can setup a basic
-module to quickly get started, simply invoke:
+module. To quickly get started simply invoke:
 
 .. code-block:: console
 
@@ -30,7 +30,7 @@ module to quickly get started, simply invoke:
 
 This will automatically create a ``my-modules`` *module directory* with an
 ``academy`` module inside. The directory can be an existing module directory
-if you want, but the module name must be unique for the directory.
+if you want, but the module name must be unique within the directory.
 
 .. patch::
     :hidden:
@@ -40,7 +40,7 @@ A demonstration module
 
 We have a "complete" module ready for installation.
 
-Although it does absolutely nothing yet we can install it:
+Although it does absolutely nothing we can install it:
 
 * start the Odoo server
 
@@ -118,8 +118,8 @@ Storing data in Odoo
 :ref:`Odoo models <reference/orm/model>` map to database tables.
 
 In the previous section we just displayed a list of string entered statically
-in the Python code. This doesn't allow modifications and persistent storage
-thereof, so we're now going to move our data to the database.
+in the Python code. This doesn't allow modifications or persistent storage
+so we'll now move our data to the database.
 
 Defining the data model
 -----------------------
@@ -139,13 +139,13 @@ left empty).
 
 .. note::
 
-    :ref:`Data files <reference/data>` (XML or CSV) have to be added to the
+    :ref:`Data files <reference/data>` (XML or CSV) must be added to the
     module manifest, Python files (models or controllers) don't but have to
     be imported from ``__init__.py`` (directly or indirectly)
 
 .. warning::
 
-    the administrator user bypasses access control, he has access to all
+    the administrator user bypasses access control, they have access to all
     models even if not given access
 
 Demonstration data
@@ -182,9 +182,9 @@ The last step is to alter model and template to use our demonstration data:
 
 Restart the server and update the module (in order to update the manifest
 and templates and load the demo file) then navigate to
-http://localhost:8069/academy/academy/. The page should look little different:
-names should simply be prefixed by a number (the database identifier for the
-teacher).
+http://localhost:8069/academy/academy/. The page should look slightly
+different: names should simply be prefixed by a number (the database
+identifier for the teacher).
 
 Website support
 ===============
@@ -383,7 +383,7 @@ let's also add views so we can see and edit a course's teacher:
 .. patch::
 
 It should also be possible to create new courses directly from a teacher's
-page, or to see all the courses a teacher gives, so add
+page, or to see all the courses they teach, so add
 :class:`the inverse relationship <openerp.fields.One2many>` to the *teachers*
 model:
 
@@ -392,8 +392,8 @@ model:
 Discussions and notifications
 -----------------------------
 
-Odoo provides technical models, which don't fulfill business needs in and of
-themselves but add capabilities to business objects without having to build
+Odoo provides technical models, which don't directly fulfill business needs
+but which add capabilities to business objects without having to build
 them by hand.
 
 One of these is the *Chatter* system, part of Odoo's email and messaging
diff --git a/doc/reference/async.rst b/doc/reference/async.rst
index c2aded839aa..d8d9c7db90f 100644
--- a/doc/reference/async.rst
+++ b/doc/reference/async.rst
@@ -7,8 +7,8 @@ Asynchronous Operations
 
 As a language (and runtime), javascript is fundamentally
 single-threaded. This means any blocking request or computation will
-blocks the whole page (and, in older browsers, the software itself
-even preventing users from switching to an other tab): a javascript
+block the whole page (and, in older browsers, the software itself
+even preventing users from switching to another tab): a javascript
 environment can be seen as an event-based runloop where application
 developers have no control over the runloop itself.
 
diff --git a/doc/reference/guidelines.rst b/doc/reference/guidelines.rst
index 6c03fd2b2e2..e2cccf19905 100644
--- a/doc/reference/guidelines.rst
+++ b/doc/reference/guidelines.rst
@@ -2,21 +2,20 @@
 
 .. highlight:: python
 
-=================
+===============
 Odoo Guidelines
-=================
+===============
 
-This page introduce the new Odoo Coding Guidelines. This guidelines
-aims to improve the quality of the code (better readability of source,
-...) but also to improve Odoo Apps ! Indeed, a proper code will ease
-the maintenance and debugging, lower the complexity and promote the
-reliability.
+This page introduce the new Odoo Coding Guidelines. These guidelines
+aim to improve the quality of the code (better readability of source,
+...) and  Odoo Apps. Indeed, proper code ought ease maintenance, aid
+debugging, lower complexity and promote reliability.
 
 Module structure
 ================
 
 Directories
-------------
+-----------
 A module is organised in a few directory :
 
 - *data/* : demo and data xml
@@ -26,24 +25,24 @@ A module is organised in a few directory :
 - *static/* : contains the web assets, separated into *css/, js/, img/, lib/, ...*
 
 File naming
-------------
+-----------
 For *views* declarations, split backend views from (frontend)
 templates in 2 differents files.
 
-For *models*, split the business logic by sets of models, in each sets
+For *models*, split the business logic by sets of models, in each set
 select a main model, this model gives its name to the set. If there is
-only one set of module, its name is the same as the module name. For
+only one model, its name is the same as the module name. For
 each set named <main_model> the following files may be created:
 
-- models/<main_model>.py
-- models/<inherited_main_model.py
-- views/<main_model>_templates.xml
-- views/<main_model>_views.xml
+- :file:`models/{<main_model>}.py`
+- :file:`models/{<inherited_main_model>}.py`
+- :file:`views/{<main_model>}_templates.xml`
+- :file:`views/{<main_model>}_views.xml`
 
-For instance, *sale* module introduce ``sale_order`` and
+For instance, *sale* module introduces ``sale_order`` and
 ``sale_order_line`` where ``sale_order`` is dominant. So the
-<main_model> files will be named *models/sale_order.py* and
-*views/sale_order_views.py*.
+``<main_model>`` files will be named :file:`models/sale_order.py` and
+:file:`views/sale_order_views.py`.
 
 
 For *data*, split them by purpose : demo or data. The filename will be
@@ -56,7 +55,7 @@ static/js/im_chat.js, static/css/im_chat.css, static/xml/im_chat.xml,
 ...). Don't link data (image, libraries) outside Odoo : don't use an
 url to an image but copy it in our codebase instead.
 
-The complete tree should looks like
+The complete tree should look like
 
 .. code-block:: text
 
@@ -98,7 +97,8 @@ The complete tree should looks like
         `-- <inherited_main_model>_views.xml
 
 
-.. note:: Filename should only use only ``[a-z0-9_]``
+.. note:: File names should only contain ``[a-z0-9_]`` (lowercase
+          alphanumerics and ``_``)
 
 .. warning:: Use correct file permissions : folder 755 and file 644.
 
@@ -143,16 +143,17 @@ Security, View and Action
 
 Use the following pattern :
 
-* For a menu : *<model_name>_menu*
-* For a view : *<model_name>_view_<view_type>*, where *view_type* is kanban, form, tree, search, ...
-* For an action : the main action respects *<model_name>_action*.
-  Others are suffixed with *_<detail>*, where *detail* is a underscore
-  lowercase string explaining a little bit the action (Should not be
-  long). This is used only if multiple action are declared for the
+* For a menu: :samp:`{<model_name>}_menu`
+* For a view: :samp:`{<model_name>}_view_{<view_type>}`, where *view_type* is
+  ``kanban``, ``form``, ``tree``, ``search``, ...
+* For an action: the main action respects :samp:`{<model_name>}_action`.
+  Others are suffixed with :samp:`_{<detail>}`, where *detail* is a
+  lowercase string briefly explaining the action.
+  This is used only if multiple actions are declared for the
   model.
-* For a group : *<model_name>_group_<group_name>* where *group_name*
-  is the name of the group, genrally 'user', 'manager', ...
-* For a rule : *<model_name>_rule_<concerned_group>* where
+* For a group: :samp:`{<model_name>}_group_{<group_name>} where *group_name*
+  is the name of the group, generally 'user', 'manager', ...
+* For a rule: :samp:`{<model_name>}_rule_{<concerned_group>}` where
   *concerned_group* is the short name of the concerned group ('user'
   for the 'model_name_group_user', 'public' for public user, 'company'
   for multi-company rules, ...).
@@ -196,12 +197,19 @@ Use the following pattern :
 
 
 
-.. note:: View name use dot notation ``my.model.view_type`` or ``my.model.view_type.inherit`` instead of *"This is the form view of My Model"*.
+.. note:: View names use dot notation ``my.model.view_type`` or
+          ``my.model.view_type.inherit`` instead of *"This is the form view of
+          My Model"*.
 
 
 Inherited XML
 ~~~~~~~~~~~~~
-The naming pattern of inherited view is *<base_view>_inherit_<current_module_name>*. A module can extend a view only one time, suffix the orginal name with *_inherit_<current_module_name>*, where *current_module_name* is the technical name of the module extending the view.
+
+The naming pattern of inherited view is
+:samp:`{<base_view>}_inherit_{<current_module_name>}`. A module may only
+extend a view once.  Suffix the orginal name with
+:samp:`_inherit_{<current_module_name>}` where *current_module_name* is the
+technical name of the module extending the view.
 
 
 .. code-block:: xml
@@ -217,7 +225,8 @@ Python
 PEP8 options
 ------------
 
-Using a linter can help to see syntax and semantic warning or error. Odoo Source Code try to respect Python standard, but some of them can be ignored.
+Using a linter can help show syntax and semantic warnings or errors. Odoo
+source code tries to respect Python standard, but some of them can be ignored.
 
 - E501: line too long
 - E301: expected 1 blank line, found 0
@@ -232,7 +241,7 @@ Imports
 -------
 The imports are ordered as
 
-#. Externals libs (One per line sorted and splitted in python stdlib)
+#. External libraries (one per line sorted and split in python stdlib)
 #. Imports of ``openerp``
 #. Imports from Odoo modules (rarely, and only if necessary)
 
@@ -255,7 +264,7 @@ Inside these 3 groups, the imported lines are alphabetically sorted.
 
 
 Idioms
--------
+------
 
 - Prefer ``%`` over ``.format()``, prefer ``%(varname)`` instead of position (This is better for translation)
 - Try to avoid generators and decorators
@@ -306,8 +315,8 @@ Symbols
 - In a Model attribute order should be
     #. Private attributes (``_name``, ``_description``, ``_inherit``, ...)
     #. Default method and ``_default_get``
-    #. Fields declarations
-    #. Compute and search methods in the same order than field declaration
+    #. Field declarations
+    #. Compute and search methods in the same order as field declaration
     #. Constrains methods (``@api.constrains``) and onchange methods (``@api.onchange``)
     #. CRUD methods (ORM overrides)
     #. Action methods
@@ -396,19 +405,18 @@ Prefix your commit with
 
 Then, in the message itself, specify the part of the code impacted by your changes (module name, lib, transversal object, ...) and a description of the changes.
 
-- Always put meaning full commit message: commit message should be
-  self explanatory (long enough) including the name of the module that
-  has been changed and the reason behind that change. Do not use
-  single words like "bugfix" or "improvements".
-
-- Avoid commits which simultaneously impacts lots of modules. Try to
-  splits into different commits where impacted modules are different
-  (It will be helpful when we are going to revert that module
-  separately).
+- Always include a meaningful commit message: it should be self explanatory
+  (long enough) including the name of the module that has been changed and the
+  reason behind the change. Do not use single words like "bugfix" or
+  "improvements".
+- Avoid commits which simultaneously impact multiple modules. Try to
+  split into different commits where impacted modules are different
+  (It will be helpful if we need to revert a module separately).
 
 .. code-block:: text
 
     [FIX] website, website_mail: remove unused alert div, fixes look of input-group-btn
+
     Bootstrap's CSS depends on the input-group-btn
     element being the first/last child of its parent.
     This was not the case because of the invisible
@@ -417,10 +425,11 @@ Then, in the message itself, specify the part of the code impacted by your chang
     [IMP] fields: reduce memory footprint of list/set field attributes
 
     [REF] web: add module system to the web client
+
     This commit introduces a new module system for the javascript code.
     Instead of using global ...
 
 
-.. note:: The long description try to explain the *why* not the
-   *what*, the *what* can be seen in the diff
+.. note:: Use the long description to explain the *why* not the
+          *what*, the *what* can be seen in the diff
 
diff --git a/doc/reference/module.rst b/doc/reference/module.rst
index 2005cf60569..94edfb2eefc 100644
--- a/doc/reference/module.rst
+++ b/doc/reference/module.rst
@@ -11,11 +11,11 @@ Modules
 Manifest
 ========
 
-The manifest file serves to both declare a python package as an Odoo module,
-and to specify a number of module metadata.
+The manifest file serves to declare a python package as an Odoo module
+and to specify module metadata.
 
 It is a file called ``__openerp__.py`` and contains a single Python
-dictionary, each dictionary key specifying a module metadatum.
+dictionary, where each key specifies module metadatum.
 
 ::
 
@@ -66,7 +66,7 @@ Available manifest fields are:
     define.
 
     When a module is installed, all of its dependencies are installed before
-    it. Likewise during modules loading.
+    it. Likewise dependencies are loaded before a module is loaded.
 ``data`` (``list(str)``)
     List of data files which must always be installed or updated with the
     module. A list of paths from the module root directory
diff --git a/doc/reference/security.rst b/doc/reference/security.rst
index b1cb05e9037..98999bf415b 100644
--- a/doc/reference/security.rst
+++ b/doc/reference/security.rst
@@ -24,12 +24,12 @@ Each access control has a model to which it grants permissions, the
 permissions it grants and optionally a group.
 
 Access controls are additive, for a given model a user has access all
-permissions granted to any of its groups: if the user belongs to group *A*
-which allows writing and group *B* which allows deleting, he can both write
+permissions granted to any of its groups: if the user belongs to one group
+which allows writing and another which allows deleting, they can both write
 and delete.
 
 If no group is specified, the access control applies to all users, otherwise
-it only applies to the users belonging to the specific group.
+it only applies to the members of the given group.
 
 Available permissions are creation (``perm_create``), searching and reading
 (``perm_read``), updating existing records (``perm_write``) and deleting
diff --git a/doc/reference/translations.rst b/doc/reference/translations.rst
index 07b87ef2b3d..9a2b6ae8b82 100644
--- a/doc/reference/translations.rst
+++ b/doc/reference/translations.rst
@@ -16,7 +16,7 @@ your module's translatable terms and may find content to work with.
 
 .. todo:: needs technical features
 
-Translations export is done via the administration interface by logging into
+Translations export is performed via the administration interface by logging into
 the backend interface and opening :menuselection:`Settings --> Translations
 --> Import / Export --> Export Translations`
 
@@ -68,7 +68,7 @@ Explicit exports
 ================
 
 When it comes to more "imperative" situations in Python code or Javascript
-code, Odoo is not able to automatically export translatable terms and they
+code, Odoo cannot automatically export translatable terms so they
 must be marked explicitly for export. This is done by wrapping a literal
 string in a function call.
 
@@ -84,11 +84,11 @@ In JavaScript, the wrapping function is generally :js:func:`openerp.web._t`:
 
 .. warning::
 
-    Only literal strings can be marked for exports, not expressions and not
+    Only literal strings can be marked for exports, not expressions or
     variables. For situations where strings are formatted, this means the
     format string must be marked, not the formatted string::
 
-        # bad, the extract may work but it will not correctly translate the text
+        # bad, the extract may work but it will not translate the text correctly
         _("Scheduled meeting with %s" % invitee.name)
 
         # good
diff --git a/doc/reference/views.rst b/doc/reference/views.rst
index 6670ac05c33..b1cc0255520 100644
--- a/doc/reference/views.rst
+++ b/doc/reference/views.rst
@@ -13,7 +13,7 @@ Common Structure
 ================
 
 View objects expose a number of fields, they are optional unless specified
-otherwise)
+otherwise.
 
 ``name`` (mandatory)
     only useful as a mnemonic/description of the view when looking for one in
@@ -22,7 +22,7 @@ otherwise)
     the model linked to the view, if applicable (it doesn't for QWeb views)
 ``priority``
     client programs can request views by ``id``, or by ``(model, type)``. For
-    the latter, all the views for the right type and model will be looked for,
+    the latter, all the views for the right type and model will be searched,
     and the one with the lowest ``priority`` number will be returned (it is
     the "default view").
 
@@ -147,7 +147,7 @@ root can have the following attributes:
 
     Defined as a mapping of colors to Python expressions. Values are of the
     form: :samp:`{color}:{expr}[;...]`. For each record, pairs are tested
-    in-order, the expression is evaluated for the record and if ``true`` the
+    in order, the expression is evaluated for the record and if ``true`` the
     corresponding color is applied to the row. If no color matches, uses the
     default text color (black).
 
@@ -572,7 +572,7 @@ Button Box
 ..........
 
 Many relevant actions or links can be displayed in the form. For example, in
-Opportunity form, the actions "Schedule a Call" and "Schedule a Meeting" take
+Opportunity form, the actions "Schedule a Call" and "Schedule a Meeting" have
 an important place in the use of the CRM. Instead of placing them in the
 "More" menu, put them directly in the sheet as buttons (on the top right) to
 make them more visible and more easily accessible.
diff --git a/doc/reference/workflows.rst b/doc/reference/workflows.rst
index a6890f05ab6..db57880436e 100644
--- a/doc/reference/workflows.rst
+++ b/doc/reference/workflows.rst
@@ -115,7 +115,7 @@ Activities
 ----------
 
 While the transitions can be seen as the control structures of the workflows,
-activities are the places where everything happens, from changing record
+activities are where everything happens, from changing record
 states to sending email.
 
 Different kinds of activities exist: ``Dummy``, ``Function``, ``Subflow``, and
diff --git a/doc/setup/deploy.rst b/doc/setup/deploy.rst
index 9b95a3adb27..9197afe839f 100644
--- a/doc/setup/deploy.rst
+++ b/doc/setup/deploy.rst
@@ -42,14 +42,14 @@ connections (from "localhost", the same machine the PostgreSQL server is
 installed on).
 
 UNIX socket is fine if you want Odoo and PostgreSQL to execute on the same
-machine, and the default when no host is provided, but if you want Odoo and
+machine, and is the default when no host is provided, but if you want Odoo and
 PostgreSQL to execute on different machines [#different-machines]_ it will
 need to `listen to network interfaces`_ [#remote-socket]_, either:
 
 * only accept loopback connections and `use an SSH tunnel`_ between the
   machine on which Odoo runs and the one on which PostgreSQL runs, then
   configure Odoo to connect to its end of the tunnel
-* accept connections to the machine on which Odoo is installed, possibly with
+* accept connections to the machine on which Odoo is installed, possibly
   over ssl (see `PostgreSQL connection settings`_ for details), then configure
   Odoo to connect over the network
 
@@ -79,7 +79,7 @@ create a new user (``odoo``) and set it as the database user.
   to be completely non-functional, the user needs to be created with
   ``no-createdb`` and the database must be owned by a different user.
 
-  .. warning:: the user also needs to *not* be a superuser
+  .. warning:: the user *must not* be a superuser
 
 HTTPS
 =====
@@ -160,7 +160,7 @@ most HTTP connections are relatively short and quickly free up their worker
 process for the next request, LiveChat require a long-lived connection for
 each client in order to implement near-real-time notifications.
 
-This is in conflict with the process-based worker model, as it's going to tie
+This is in conflict with the process-based worker model, as it will tie
 up worker processes and prevent new users from accessing the system. However,
 those long-lived connections do very little and mostly stay parked waiting for
 notifications.