Fixed #30573 -- Rephrased documentation to avoid words that minimise the involved difficulty.

This patch does not remove all occurrences of the words in question.
Rather, I went through all of the occurrences of the words listed
below, and judged if they a) suggested the reader had some kind of
knowledge/experience, and b) if they added anything of value (including
tone of voice, etc). I left most of the words alone. I looked at the
following words:

- simply/simple
- easy/easier/easiest
- obvious
- just
- merely
- straightforward
- ridiculous

Thanks to Carlton Gibson for guidance on how to approach this issue, and
to Tim Bell for providing the idea. But the enormous lion's share of
thanks go to Adam Johnson for his patient and helpful review.

Author: rixx

docs/faq/admin.txt

@@ -78,9 +78,9 @@ modules to the page via the model's class Admin :ref:`js parameter
 pointing to JavaScript modules that will be included within the admin form via
 a ``<script>`` tag.
 
-If you want more flexibility than simply tweaking the auto-generated forms,
-feel free to write custom views for the admin. The admin is powered by Django
-itself, and you can write custom views that hook into the authentication
+If you want more flexibility than is feasible by tweaking the auto-generated
+forms, feel free to write custom views for the admin. The admin is powered by
+Django itself, and you can write custom views that hook into the authentication
 system, check permissions and do whatever else they need to do.
 
 If you want to customize the look-and-feel of the admin interface, read the

docs/faq/contributing.txt

@@ -84,7 +84,7 @@ of a larger problem. While we can spend time writing, testing and applying
 lots of little patches, sometimes the right solution is to rebuild. If a
 rebuild or refactor of a particular component has been proposed or is
 underway, you may find that bugs affecting that component will not get as much
-attention. Again, this is just a matter of prioritizing scarce resources. By
+attention. Again, this is a matter of prioritizing scarce resources. By
 concentrating on the rebuild, we can close all the little bugs at once, and
 hopefully prevent other little bugs from appearing in the future.
 
@@ -93,7 +93,7 @@ bug regularly, it doesn't necessarily follow that every single Django user
 will hit the same bug. Different users use Django in different ways, stressing
 different parts of the code under different conditions. When we evaluate the
 relative priorities, we are generally trying to consider the needs of the
-entire community, not just the severity for one particular user. This doesn't
-mean that we think your problem is unimportant -- just that in the limited
-time we have available, we will always err on the side of making 10 people
-happy rather than making 1 person happy.
+entire community, instead of prioritizing the impact on one particular user.
+This doesn't mean that we think your problem is unimportant -- just that in the
+limited time we have available, we will always err on the side of making 10
+people happy rather than making a single person happy.

docs/faq/models.txt

@@ -8,7 +8,7 @@ How can I see the raw SQL queries Django is running?
 ====================================================
 
 Make sure your Django :setting:`DEBUG` setting is set to ``True``.
-Then, just do this::
+Then do this::
 
     >>> from django.db import connection
     >>> connection.queries
@@ -32,7 +32,7 @@ same interface on each member of the ``connections`` dictionary::
     >>> connections['my_db_alias'].queries
 
 If you need to clear the query list manually at any point in your functions,
-just call ``reset_queries()``, like this::
+call ``reset_queries()``, like this::
 
     from django.db import reset_queries
     reset_queries()
@@ -61,8 +61,8 @@ But this isn't an issue in practice, because there's nothing stopping you from
 adding other constraints (using the ``unique_together`` model option or
 creating the constraint directly in your database), and enforcing the
 uniqueness at that level. Single-column primary keys are needed for things such
-as the admin interface to work; e.g., you need a simple way of being able to
-specify an object to edit or delete.
+as the admin interface to work; e.g., you need a single value to specify
+an object to edit or delete.
 
 Does Django support NoSQL databases?
 ====================================

docs/faq/usage.txt

@@ -61,9 +61,9 @@ Using a :class:`~django.db.models.FileField` or an
 How do I make a variable available to all my templates?
 =======================================================
 
-Sometimes your templates just all need the same thing. A common example would
-be dynamically-generated menus. At first glance, it seems logical to simply
-add a common dictionary to the template context.
+Sometimes your templates all need the same thing. A common example would be
+dynamically generated menus. At first glance, it seems logical to add a common
+dictionary to the template context.
 
-The correct solution is to use a ``RequestContext``. Details on how to do this
-are here: :ref:`subclassing-context-requestcontext`.
+The best way to do this in Django is to use a ``RequestContext``. Details on
+how to do this are here: :ref:`subclassing-context-requestcontext`.

docs/howto/auth-remote-user.txt

@@ -111,8 +111,8 @@ Using ``REMOTE_USER`` on login pages only
 
 The ``RemoteUserMiddleware`` authentication middleware assumes that the HTTP
 request header ``REMOTE_USER`` is present with all authenticated requests. That
-might be expected and practical when Basic HTTP Auth with ``htpasswd`` or other
-simple mechanisms are used, but with Negotiate (GSSAPI/Kerberos) or other
+might be expected and practical when Basic HTTP Auth with ``htpasswd`` or
+similar mechanisms are used, but with Negotiate (GSSAPI/Kerberos) or other
 resource intensive authentication methods, the authentication in the front-end
 HTTP server is usually only set up for one or a few login URLs, and after
 successful authentication, the application is supposed to maintain the

docs/howto/custom-lookups.txt

@@ -9,10 +9,10 @@ filtering (for example, ``exact`` and ``icontains``). This documentation
 explains how to write custom lookups and how to alter the working of existing
 lookups. For the API references of lookups, see the :doc:`/ref/models/lookups`.
 
-A simple lookup example
-=======================
+A lookup example
+================
 
-Let's start with a simple custom lookup. We will write a custom lookup ``ne``
+Let's start with a small custom lookup. We will write a custom lookup ``ne``
 which works opposite to ``exact``. ``Author.objects.filter(name__ne='Jack')``
 will translate to the SQL:
 
@@ -24,8 +24,7 @@ This SQL is backend independent, so we don't need to worry about different
 databases.
 
 There are two steps to making this work. Firstly we need to implement the
-lookup, then we need to tell Django about it. The implementation is quite
-straightforward::
+lookup, then we need to tell Django about it::
 
   from django.db.models import Lookup
 
@@ -38,10 +37,10 @@ straightforward::
           params = lhs_params + rhs_params
           return '%s <> %s' % (lhs, rhs), params
 
-To register the ``NotEqual`` lookup we will just need to call
-``register_lookup`` on the field class we want the lookup to be available. In
-this case, the lookup makes sense on all ``Field`` subclasses, so we register
-it with ``Field`` directly::
+To register the ``NotEqual`` lookup we will need to call ``register_lookup`` on
+the field class we want the lookup to be available for. In this case, the lookup
+makes sense on all ``Field`` subclasses, so we register it with ``Field``
+directly::
 
   from django.db.models.fields import Field
   Field.register_lookup(NotEqual)
@@ -94,8 +93,8 @@ Finally we combine the parts into an SQL expression with ``<>``, and supply all
 the parameters for the query. We then return a tuple containing the generated
 SQL string and the parameters.
 
-A simple transformer example
-============================
+A transformer example
+=====================
 
 The custom lookup above is great, but in some cases you may want to be able to
 chain lookups together. For example, let's suppose we are building an
@@ -241,10 +240,10 @@ want the transformation to be applied to both the left-hand side and the
 right-hand side. For instance, if you want to filter a queryset based on the
 equality of the left and right-hand side insensitively to some SQL function.
 
-Let's examine the simple example of case-insensitive transformation here. This
-transformation isn't very useful in practice as Django already comes with a bunch
-of built-in case-insensitive lookups, but it will be a nice demonstration of
-bilateral transformations in a database-agnostic way.
+Let's examine case-insensitive transformations here. This transformation isn't
+very useful in practice as Django already comes with a bunch of built-in
+case-insensitive lookups, but it will be a nice demonstration of bilateral
+transformations in a database-agnostic way.
 
 We define an ``UpperCase`` transformer which uses the SQL function ``UPPER()`` to
 transform the values before comparison. We define

docs/howto/custom-management-commands.txt

@@ -10,9 +10,9 @@ distributing. In this document, we will be building a custom ``closepoll``
 command for the ``polls`` application from the
 :doc:`tutorial</intro/tutorial01>`.
 
-To do this, just add a ``management/commands`` directory to the application.
-Django will register a ``manage.py`` command for each Python module in that
-directory whose name doesn't begin with an underscore. For example::
+To do this, add a ``management/commands`` directory to the application. Django
+will register a ``manage.py`` command for each Python module in that directory
+whose name doesn't begin with an underscore. For example::
 
     polls/
         __init__.py

docs/howto/custom-model-fields.txt

@@ -50,7 +50,7 @@ something like this::
 
 .. _Bridge: https://en.wikipedia.org/wiki/Contract_bridge
 
-This is just an ordinary Python class, with nothing Django-specific about it.
+This is an ordinary Python class, with nothing Django-specific about it.
 We'd like to be able to do things like this in our models (we assume the
 ``hand`` attribute on the model is an instance of ``Hand``)::
 
@@ -81,11 +81,12 @@ Background theory
 Database storage
 ----------------
 
-The simplest way to think of a model field is that it provides a way to take a
-normal Python object -- string, boolean, ``datetime``, or something more
-complex like ``Hand`` -- and convert it to and from a format that is useful
-when dealing with the database (and serialization, but, as we'll see later,
-that falls out fairly naturally once you have the database side under control).
+Let's start with model fields. If you break it down, a model field provides a
+way to take a normal Python object -- string, boolean, ``datetime``, or
+something more complex like ``Hand`` -- and convert it to and from a format
+that is useful when dealing with the database. (Such a format is also useful
+for serialization, but as we'll see later, that is easier once you have the
+database side under control).
 
 Fields in a model must somehow be converted to fit into an existing database
 column type. Different databases provide different sets of valid column types,
@@ -94,8 +95,7 @@ with. Anything you want to store in the database must fit into one of
 those types.
 
 Normally, you're either writing a Django field to match a particular database
-column type, or there's a fairly straightforward way to convert your data to,
-say, a string.
+column type, or you will need a way to convert your data to, say, a string.
 
 For our ``Hand`` example, we could convert the card data to a string of 104
 characters by concatenating all the cards together in a pre-determined order --
@@ -180,16 +180,16 @@ card values plus their suits; 104 characters in total.
     with. For example, you can pass both
     :attr:`~django.db.models.Field.editable` and
     :attr:`~django.db.models.DateField.auto_now` to a
-    :class:`django.db.models.DateField` and it will simply ignore the
+    :class:`django.db.models.DateField` and it will ignore the
     :attr:`~django.db.models.Field.editable` parameter
     (:attr:`~django.db.models.DateField.auto_now` being set implies
     ``editable=False``). No error is raised in this case.
 
     This behavior simplifies the field classes, because they don't need to
-    check for options that aren't necessary. They just pass all the options to
+    check for options that aren't necessary. They pass all the options to
     the parent class and then don't use them later on. It's up to you whether
     you want your fields to be more strict about the options they select, or to
-    use the simpler, more permissive behavior of the current fields.
+    use the more permissive behavior of the current fields.
 
 The ``Field.__init__()`` method takes the following parameters:
 
@@ -241,11 +241,11 @@ then there's no need to write a new ``deconstruct()`` method. If, however,
 you're changing the arguments passed in ``__init__()`` (like we are in
 ``HandField``), you'll need to supplement the values being passed.
 
-The contract of ``deconstruct()`` is simple; it returns a tuple of four items:
-the field's attribute name, the full import path of the field class, the
-positional arguments (as a list), and the keyword arguments (as a dict). Note
-this is different from the ``deconstruct()`` method :ref:`for custom classes
-<custom-deconstruct-method>` which returns a tuple of three things.
+``deconstruct()`` returns a tuple of four items: the field's attribute name,
+the full import path of the field class, the positional arguments (as a list),
+and the keyword arguments (as a dict). Note this is different from the
+``deconstruct()`` method :ref:`for custom classes <custom-deconstruct-method>`
+which returns a tuple of three things.
 
 As a custom field author, you don't need to care about the first two values;
 the base ``Field`` class has all the code to work out the field's attribute
@@ -307,8 +307,8 @@ mind that people will be reconstructing your field from the serialized version
 for quite a while (possibly years), depending how long your migrations live for.
 
 You can see the results of deconstruction by looking in migrations that include
-the field, and you can test deconstruction in unit tests by just deconstructing
-and reconstructing the field::
+the field, and you can test deconstruction in unit tests by deconstructing and
+reconstructing the field::
 
     name, path, args, kwargs = my_field_instance.deconstruct()
     new_instance = MyField(*args, **kwargs)
@@ -349,10 +349,10 @@ As always, you should document your field type, so users will know what it is.
 In addition to providing a docstring for it, which is useful for developers,
 you can also allow users of the admin app to see a short description of the
 field type via the :doc:`django.contrib.admindocs
-</ref/contrib/admin/admindocs>` application. To do this simply provide
-descriptive text in a :attr:`~Field.description` class attribute of your custom
-field. In the above example, the description displayed by the ``admindocs``
-application for a ``HandField`` will be 'A hand of cards (bridge style)'.
+</ref/contrib/admin/admindocs>` application. To do this provide descriptive
+text in a :attr:`~Field.description` class attribute of your custom field. In
+the above example, the description displayed by the ``admindocs`` application
+for a ``HandField`` will be 'A hand of cards (bridge style)'.
 
 In the :mod:`django.contrib.admindocs` display, the field description is
 interpolated with ``field.__dict__`` which allows the description to
@@ -393,8 +393,8 @@ Once you have ``MytypeField``, you can use it in any model, just like any other
 If you aim to build a database-agnostic application, you should account for
 differences in database column types. For example, the date/time column type
 in PostgreSQL is called ``timestamp``, while the same column in MySQL is called
-``datetime``. The simplest way to handle this in a :meth:`~Field.db_type`
-method is to check the ``connection.settings_dict['ENGINE']`` attribute.
+``datetime``. You can handle this in a :meth:`~Field.db_type` method by
+checking the ``connection.settings_dict['ENGINE']`` attribute.
 
 For example::
 
@@ -431,7 +431,7 @@ sense to have a ``CharMaxlength25Field``, shown here::
         my_field = CharMaxlength25Field()
 
 The better way of doing this would be to make the parameter specifiable at run
-time -- i.e., when the class is instantiated. To do that, just implement
+time -- i.e., when the class is instantiated. To do that, implement
 ``Field.__init__()``, like so::
 
     # This is a much more flexible example.
@@ -730,7 +730,7 @@ accessed, and what methods are available. It lives at
 :doc:`file documentation </ref/files/file>`.
 
 Once a subclass of ``File`` is created, the new ``FileField`` subclass must be
-told to use it. To do so, simply assign the new ``File`` subclass to the special
+told to use it. To do so, assign the new ``File`` subclass to the special
 ``attr_class`` attribute of the ``FileField`` subclass.
 
 A few suggestions