[docs] Improves confusing idempotence rant

docs/glossary.rst

@@ -6,6 +6,18 @@ Glossary
 .. glossary::
     :sorted:
 
+    acknowledged
+        Workers acknowledge messages to signify that a message has been
+        handled.  Failing to acknowledge a message
+        will cause the message to be redelivered.   Exactly when a
+        transaction is considered a failure varies by transport.  In AMQP the
+        transaction fails when the connection/channel is closed (or lost),
+        but in Redis/SQS the transaction times out after a configurable amount
+        of time (the ``visibility_timeout``).
+
+    ack
+        Short for :term:`acknowledged`.
+
     request
         Task messages are converted to *requests* within the worker.
         The request information is also available as the task's
@@ -27,3 +39,15 @@ Glossary
         it's arguments and what queue it was delivered to.
         It can be accessed as the tasks ``request`` attribute.
         See :ref:`task-request-info`
+
+    idempotent
+        Idempotence is a mathematical property that describes a function that
+        can be called multiple times without changing the result.
+        Practically it means that a function can be repeated many times without
+        unintented effects, but not necessarily side-effect free in the pure
+        sense (compare to :term:`nullipotent`).
+
+    nullipotent
+        describes a function that will have the same effect, and give the same
+        result, even if called zero or multiple times (side-effect free).
+        A stronger version of :term:`idempotent`.

docs/userguide/tasks.rst

@@ -6,30 +6,28 @@
 
 Tasks are the building blocks of Celery applications.
 
-A task can be created out of any callable and defines what happens
-when the worker receives a particular message.
+A task is a class that can be created out of any callable. It performs
+dual roles in that it defines both what happens when a task is
+called (sends a message), and what happens when a worker receives that message.
 
-Every task has unique name which is referenced in the message,
-so that the worker can find the right task to execute.
+Every task class has a unique name, and this name is referenced in messages
+so that the worker can find the right function to execute.
 
-It's not a requirement, but it's a good idea to keep your tasks
-*idempotent*.  Idempotence means that a task can be applied multiple
-times without changing the result.
-
-This is important because the task message will not disappear
-until the message has been *acknowledged*. A worker can reserve
-many messages in advance and even if the worker is killed -- caused by a power failure
+A task message does not disappear
+until the message has been :term:`acknowledged` by a worker. A worker can reserve
+many messages in advance and even if the worker is killed -- caused by power failure
 or otherwise -- the message will be redelivered to another worker.
 
-But the worker cannot know if your tasks are idempotent, so the default
-behavior is to acknowledge the message in advance just before it's executed,
-this way a task that has been started will not be executed again.
+Ideally task functions should be :term:`idempotent`, which means that
+the function will not cause unintented effects even if called
+multiple times with the same arguments.
+Since the worker cannot detect if your tasks are idempotent, the default
+behavior is to acknowledge the message in advance, before it's executed,
+so that a task that has already been started is never executed again..
 
 If your task is idempotent you can set the :attr:`acks_late` option
-to have the worker acknowledge the message *after* that task has been
-executed instead.  This way the task will be redelivered to another
-worker, even if the task has already started executing before.
-See also the FAQ entry :ref:`faq-acks_late-vs-retry`.
+to have the worker acknowledge the message *after* the task returns
+instead.  See also the FAQ entry :ref:`faq-acks_late-vs-retry`.
 
 --