Improve language in all sections of the index page.

doc/index.rst

@@ -22,7 +22,7 @@ Getting Started
 =================
 
 Flask-Admin lets you build complicated interfaces by grouping individual views
-together in classes: Each view that you see on the frontend, represents a
+together in classes: Each web page you see on the frontend, represents a
 method on a class that has explicitly been added to the interface.
 
 These view classes are especially helpful when they are tied to particular
@@ -34,7 +34,7 @@ class for each of your models.
 Initialization
 --------------
 
-The first step, is to initialise an empty admin interface on your Flask app::
+To get started, the first step, is to initialise an empty admin interface on your Flask app::
 
     from flask import Flask
     from flask_admin import Admin
@@ -46,8 +46,10 @@ The first step, is to initialise an empty admin interface on your Flask app::
 
     app.run()
 
-Here, both the *name* and *template_mode* parameters are optional. If you start this application and navigate to `http://localhost:5000/admin/ <http://localhost:5000/admin/>`_,
-you should see an empty "Home" page with a navigation bar on top, and the *name* that you specified.
+Here, both the *name* and *template_mode* parameters are optional.
+
+If you start this application and navigate to `http://localhost:5000/admin/ <http://localhost:5000/admin/>`_,
+you should see an empty page with a navigation bar on top.
 
 Adding Model Views
 ----------------------
@@ -72,10 +74,10 @@ Straight out of the box, this gives you a set of fully featured *CRUD* views for
 There are many options available for customizing the display and functionality of these builtin view.
 For more details on that, see :ref:`customising-builtin-views`.
 
-Customising the index page
+Adding Content to the Index Page
 ------------------------------------
 The first thing you'll notice when you visit `http://localhost:5000/admin/ <http://localhost:5000/admin/>`_
-is that it's just an empty page with a navigation menu. To add some content to this page, save the following text to a file in `my_app/templates/admin/index.html`::
+is that it's just an empty page with a navigation menu. To add some content to this page, save the following text as `admin/index.html` in your project's `templates` directory::
 
     {% extends 'admin/master.html' %}
 
@@ -83,7 +85,7 @@ is that it's just an empty page with a navigation menu. To add some content to t
       <p>Hello world</p>
     {% endblock %}
 
-This will override the builtin index template, but still give you the builtin navigation menu. So, now you can add any content to the index page that makes sense for your app.
+This will override the default index template, but still give you the navigation menu. So, now you can add any content to the index page that makes sense for your app.
 
 ****
 
@@ -114,16 +116,15 @@ How you implement the logic is up to you, but if you were to use a low-level lib
 `Flask-Login <https://flask-login.readthedocs.org/>`_, then restricting access
 could be as simple as::
 
-    class MyModelView(sqla.ModelView):
+    class BaseModelView(sqla.ModelView):
 
         def is_accessible(self):
             return login.current_user.is_authenticated()
 
-However, you would still need to implement all of the relevant login /
-registration views yourself.
+However, you would still need to implement all of the relevant login,
+registration and account management views yourself.
 
-If you like this approach, then have a look at the example at
-https://github.com/flask-admin/Flask-Admin/tree/master/examples/auth-flask-login.
+For a basic example of this, have a look at https://github.com/flask-admin/Flask-Admin/tree/master/examples/auth-flask-login.
 
 Using Flask-Security
 --------------------------------
@@ -131,10 +132,10 @@ Using Flask-Security
 If you want to get started quicker, you could
 use `Flask-Security <https://pythonhosted.org/Flask-Security/>`_,
 which is a higher-level library. It comes with lots of builtin views for doing
-common things like registration, login, email address confirmation, password resets, etc.
+common things like user registration, login, email address confirmation, password resets, etc.
 
-The complicated bit, is making the builtin Flask-Security views work together with the
-Flask-Admin templates, to create a consistent experience for your users. To
+The only complicated bit, is making the builtin Flask-Security views integrate smoothly with the
+Flask-Admin templates to create a consistent user experience. To
 do this, you will need to override the builtin Flask-Security templates and have them
 extend the Flask-Admin base template by adding the following to the top
 of each file::
@@ -166,9 +167,9 @@ Customising Builtin Views
 =================================
 
 The builtin `ModelView` class is great for getting started quickly. But you'll want
-to adapt it's functionality
-to suit your particular models. To do this, there's a whole host of configuration
-attributes that you can set either globally, or just for specific models.
+to configure its functionality
+to suit your particular models. This is done by setting values for the configuration
+attributes that are made available on the `ModelView` class.
 
 To specify some global configuration parameters, you can subclass `ModelView`, and then use that
 subclass when adding your models to the interface::
@@ -196,12 +197,12 @@ Or, in much the same way, you can specify options for a single model at a time::
     admin.add_view(PostView(Post, db.session))
 
 
-View configuration attributes
------------------------------
+`ModelView` Configuration Attributes
+-----------------------------------
 
-For a complete list of all the options that are available, have a look at the
-API documentation for :meth:`~flask_admin.model.BaseModelView`. Here we are
-just highlighting some of the most useful ones.
+For a complete list of the attributes that are defined, have a look at the
+API documentation for :meth:`~flask_admin.model.BaseModelView`. But, here follows
+some of the most commonly used ones:
 
 To disable some of the basic CRUD operations, set any of these boolean parameters::
 
@@ -210,15 +211,15 @@ To disable some of the basic CRUD operations, set any of these boolean parameter
     can_delete = True
 
 
-Common List view options
-**************************
+Configuring the List View
+****************************
 
 Removing some columns from the list view is easy, just use something like::
 
     column_exclude_list = ['password', ]
 
 To make some of your columns searchable, or to use them for filtering, specify
-a list of column names, e.g.::
+a list of column names::
 
     column_searchable_list = ['name', 'email']
     column_filters = ['country', ]
@@ -227,10 +228,10 @@ For a faster editing experience, make some of the columns editable in the list v
 
     column_editable_list = ['name', 'last_name']
 
-Common Form view options
-**************************
+Configuring the Create & Edit Views
+************************************
 
-You can restrict the values of a text-field by specifying a list of choices::
+You can restrict the possible values for a text-field by specifying a list of choices::
 
     form_choices = {
         'title': [
@@ -242,11 +243,11 @@ You can restrict the values of a text-field by specifying a list of choices::
         ]
     }
 
-To remove some fields from the forms::
+To remove some fields from the create and edit forms::
 
-    form_excluded_columns = ('last_name', 'email')
+    form_excluded_columns = ['last_name', 'email']
 
-To specify arguments for rendering the WTForms fields::
+To specify arguments to the WTForms fields when they are being rendered::
 
     form_args = {
         'name': {
@@ -255,8 +256,8 @@ To specify arguments for rendering the WTForms fields::
         }
     }
 
-Or, to go one level deeper, you can specify arguments for the widgets used to
-render those fields. For example::
+And, to go one level deeper, you can specify arguments to the widgets used to
+render those fields::
 
     form_widget_args = {
         'description': {
@@ -270,23 +271,27 @@ related models loaded via ajax, using::
 
     form_ajax_refs = {
         'user': {
-            'fields': ('first_name', 'last_name', 'email')
+            'fields': ['first_name', 'last_name', 'email']
             'page_size': 10
         }
     }
 
-Overriding the default templates
+Changing the Look & Feel
 ---------------------------------
 
-You can override any of the builtin Flask-Admin templates by simply copying them
-into `templates/admin/` in your project directory. This gives you absolute
-control over the look & feel of the admin interface, but with one drawback: it
-can make life difficult for you when you eventually want to upgrade the version
-of Flask-Admin that you are using.
+To take full control over the look & feel of the admin interface, you can override
+all of the builtin templates. Just keep in mind that the templates will change slightly
+from one Flask-Admin version to the next, so once you start overriding them, you
+need to take care when upgrade your package version.
+
+To override any of the builtin templates, simply copy them from
+the Flask-Admin source into `templates/admin/` in your project directory.
+As long as the filenames stay the same, the templates in your project directory should
+automatically take precedence over the builtin ones.
 
 If you want to keep your custom templates in some other location, then you need
 to remember to reference them from the ModelView classes where you intend to
-use them, e.g.::
+use them, for example::
 
     class BaseModelView(ModelView):
         list_template = 'base_list.html'
@@ -294,16 +299,16 @@ use them, e.g.::
         edit_template = 'base_edit.html'
 
 Have a look at the `layout` example at https://github.com/flask-admin/flask-admin/tree/master/examples/layout
-if you want to see how to take full stylistic control.
+to see how you can take full stylistic control over the admin interface.
 
-Replacing specific form fields
+Replacing Individual Form Fields
 ------------------------------------------
 
-Individual form fields can be replaced completely by specifying the `form_overrides` attribute.
-You can use this to add a rich text editor, or to handle
-file / image uploads that need to be tied to a field in one of your models.
+The `form_overrides` attribute allows you to replace individual fields within a form.
+A comon use-case for this would be to add a rich text editor, or to handle
+file / image uploads that need to be tied to a field in your model.
 
-Rich-text fields
+Rich-Text Fields
 **********************
 To handle complicated text content, use `CKEditor <http://ckeditor.com/>`_ by subclassing some of the builtin WTForms classes as follows::
 
@@ -330,7 +335,7 @@ To handle complicated text content, use `CKEditor <http://ckeditor.com/>`_ by su
 
 For this to work, you would also need to create a template that extends the default
 functionality by including the necessary CKEditor javascript on the `create` and
-`edit` pages. Save this in `templates/ckeditor.html::
+`edit` pages. Save this in `templates/ckeditor.html`::
 
     {% extends 'admin/model/edit.html' %}
 
@@ -339,27 +344,28 @@ functionality by including the necessary CKEditor javascript on the `create` and
       <script src="http://cdnjs.cloudflare.com/ajax/libs/ckeditor/4.0.1/ckeditor.js"></script>
     {% endblock %}
 
-File & Image fields
+File & Image Fields
 *******************
 
-For handling File & Image fields, have a look a the example at
-https://github.com/flask-admin/Flask-Admin/tree/master/examples/forms.
+Flask-Admin comes with a builtin `FileUploadField` and `ImageUploadField`. To make use
+of them, you'll need to specify an upload directory, and add them to the forms in question.
+Image handling also requires you to have `Pillow <https://pypi.python.org/pypi/Pillow/2.8.2>`_ installed.
 
-You'll need to specify an upload directory, and then use either `FileUploadField` or
-`ImageUploadField` to override the field in question.
+Have a look a the example at
+https://github.com/flask-admin/Flask-Admin/tree/master/examples/forms.
 
-If you just want to manage static files, without tying them to a database model, then
-rather use the :ref:`File-Admin<file-admin>` plugin.
+If you just want to manage static files in a directory, without tying them to a database model, then
+rather use the handy :ref:`File-Admin<file-admin>` plugin.
 
 ****
 
-Adding your own views
+Adding Your Own Views
 ======================
 For situations where your requirements are really specific, and you struggle to meet
-them with the builtin :class:`~flask_admin.model.ModelView` class: Flask-Admin makes it really easy for you to
-take full control and ass some views yourself.
+them with the builtin :class:`~flask_admin.model.ModelView` class: Flask-Admin makes it easy for you to
+take full control and add your own views to the interface.
 
-Standalone views
+Standalone Views
 ------------------
 To add a set of standalone views, that are not tied to any particular model, you can extend the
 :class:`~flask_admin.base.BaseView` class, and define your own view methods on it. For
@@ -375,8 +381,8 @@ example, to add a page that displays some analytics data from a 3rd-party API::
     admin.add_view(CustomView(name='Analytics'))
 
 This will add a link to the navbar, from where your view can be accessed. Notice that
-it is served at the root URL, '/'. This is a restriction on standalone views: each view class needs
-to serve a view at its root.
+it is served at '/', the root URL. This is a restriction on standalone views: at the very minimum, each view class needs
+at least one method, that serves a view at the root URL.
 
 The `analytics_index.html` template for the example above, could look something like::
 
@@ -388,12 +394,12 @@ The `analytics_index.html` template for the example above, could look something
 By extending the *admin/master.html* template, you can maintain a consistent user experience,
 even while having tight control over your page's content.
 
-Overriding the builtin views
+Overriding the Builtin Views
 ------------------------------------
 
-If you want most of the builtin ModelView functionality, but you want to have your own view
-in place of the default `create`, `edit`, or `list` view. Then you can simply
-override the view in question, and all the links to it will still function as you would expect::
+There may be some scenarios where you want most of the builtin ModelView
+functionality, but you want to replace one of the default `create`, `edit`, or `list` views.
+For this you could override only the view in question, and all the links to it will still function as you would expect::
 
     from flask_admin.contrib.sqla import ModelView