redo diagram in dot

1 files changed, 43 insertions, 23 deletions

diff --git a/design-documents/037-wallet-transactions-lifecycle.rst b/design-documents/037-wallet-transactions-lifecycle.rst
index 8a8df2e2..64ec242a 100644
--- a/design-documents/037-wallet-transactions-lifecycle.rst
+++ b/design-documents/037-wallet-transactions-lifecycle.rst
@@ -23,7 +23,7 @@ and aborting have transaction-specific sub-states, denoted by ``state(substate)`
 
 ``initial``: The initial state is the result a user interaction. A transaction
 may have more than one initial state (if it is started in multiple ways) or none
-(if it's the result of another process)
+(if it's the result of another process).
 
 ``pending``: A pending transaction waits for some external event/service.
 The transaction stays pending until its change on the wallet's material balance
@@ -31,12 +31,13 @@ is finished. Any pending state can be suspended and resumed.
 
 There are some other distinctions for pending transactions:
 
-* long-polling vs exponential backoff: A pending transaction is either waiting
+* long-polling vs. exponential backoff: A pending transaction is either waiting
   on an external service by making a long-polling request or by repeating requests
   with exponential back-off.
 * ``lastError``: A pending transaction is either clean (i.e. the network interaction
   is literally active in transmission or the external service successfully
-  communicated that it is not ready yet) or has a ``lastError``, which is a ``TalerErrorDetails``
+  communicated that it is not ready yet and this is perfectly normal)
+  or has a ``lastError``, which is a ``TalerErrorDetails``
   object with details about what happened during the last attempt to proceed
   with the transaction.
 
@@ -47,7 +48,7 @@ never has a ``lastError`` but is considered successful.
 complete the transaction, the wallet is taking active steps to abort it. The ``lastError``
 indicates errors the wallet experienced while taking active steps to abort the transaction.
 
-``aborted``: Similar to a ``done`` transaction, but the transaction was successfully aborted
+``aborted``: Similar to ``done``, but the transaction was successfully aborted
 instead of successfully finished. It will have the information of when (timestamp) it was
 aborted and in which pending sub-state the abort action was initiated. Also, we can
 include more information information relevant to the transaction in `abortReason`
@@ -55,11 +56,11 @@ include more information information relevant to the transaction in `abortReason
 ``suspended``: Similar to a ``aborted`` transaction, but the transaction was could be
 resumed and may then still succeed.
 
-``failed``: Similar to ``done``, but the transaction could not even be aborted successfully.
+``failed``: Similar to ``done``, but the transaction could not even be aborted properly.
 
 ``deleted``: A ``deleted`` state is always a final state.  We only use this
 state for illustrative purposes. In the implementation, the data associated
-with the transaction would be deleted.
+with the transaction would be literally deleted.
 
 
 Common Transitions
@@ -67,12 +68,12 @@ Common Transitions
 
 Transitions are actions or other events.
 
-``[action:delete]``: Deleting a transaction (also called "forgetting" in the UI)
-completely deletes the transaction in the database.  Depending on the type of
+``[action:delete]``: Deleting a transaction
+completely deletes the transaction from the database.  Depending on the type of
 transaction, some of the other data *resulting* from the transaction might
 still survive deletion. For example, deleting a withdrawal transaction does not
 delete already successfully withdrawn coins. Deleting is only safe (no money lost)
-on initial and final state (failed, aborted, done)
+on initial and final states (failed, aborted, done).
 
 ``[action:retry]``: Retrying a transaction *(1.)* stops ongoing long-polling
 requests for the transaction *(2.)* resets the retry timeout *(3.)* re-runs the
@@ -84,35 +85,51 @@ states: ``pending(*)`` and ``aborting(*)``.
    Should we show the retry timeout in the UI somewhere?  Should we show it in dev mode?
 
    SEBASJM: Since the wallet will retry anyway, maybe is better if we replace the "retry"
-   button with a "try now" button and a side text "retrying in xxx seconds"
+   button with a "try now" button and a side text "retrying in xxx seconds".
+
+   CG: Instead of a side text, this *might* make a good mouse-over hint for
+   a "retry" (or "try now") button. I would not make this overly visible with
+   side-text as the information is not that important. The text should also be
+   "retrying next at XXX" using an absolute time XXX --- otherwise the UI would
+   be way too busy recomputing/updating all of these strings: Using an absolute time,
+   we only have to redraw anything once a retry actually happened. Given that
+   retries should basically never be > 24h (we can impose a hard cap), the absolute
+   time can just be in the format HH:MM:SS (without day).
 
 ``[action:abort]``: Aborting a transaction either directly stops processing for the
-transaction and puts it in an ``aborted`` state or starts the necessary steps to
+transaction and puts it in an ``aborted`` state, or starts the necessary steps to
 actively abort the transaction (e.g. to avoid losing money) and puts it in an
 ``aborting`` state.
 
-``[action:suspend]``: Suspends a pending transaction, stopping any associated network activities, but with a chance of trying
-again at a later time. This could be useful if a user needs to save battery power or bandwidth and an operation is expected
-to take longer (such as a backup, recovery or very large withdrawal operation).
+``[action:suspend]``: Suspends a pending transaction, stopping any associated
+network activities, but with a chance of trying again at a later time. This
+could be useful if a user needs to save battery power or bandwidth and an
+operation is expected to take longer (such as a backup, recovery or very large
+withdrawal operation).
 
-``[action:resume]``: Suspended transactions may be resumed, placing them back into a pending state.
+``[action:resume]``: Suspended transactions may be resumed, placing them back
+into a pending state.
 
-``[action:abort-force]``: Directly puts an ``aborting`` transaction into the ``failed`` state.
+``[action:abort-force]``: Directly puts an ``aborting`` transaction into the
+``failed`` state.
 
 
-Whether aborting or resuming is possible depends on the transaction type, and usually only one
-of the two choices should be offered.
+Whether aborting or resuming are possible depends on the transaction type, and
+usually only one of the two choices should be offered.
 
 
-.. image:: ../transaction-common-states.svg
+.. image:: ../transaction-common-states.png
   :width: 400
 
-Boxed label means end state, where it is safe to delete the transaction record since no work is due.
 
-Blue arrows means mean user-triggered actions
+Boxed labels indicate an end state in which it is safe to delete the
+transaction record since no work is due.
+
+Blue arrows are used for user-triggered actions (via UI buttons).
+
 
 Common pending sub-states
----------------------------------
+-------------------------
 
 During the pending state the transaction can go through several sub-states before
 reaching a final state. Some of this sub-states are shared between different
@@ -627,7 +644,10 @@ The payment succeed but if auto-refund-check is active it will be checking for r
 Alternatives
 ============
 
-* each transaction could be treated completely separately
+* Each transaction could be treated completely separately; however, uniform
+  terminology for actions (and thus button labels) is likely more helpful for
+  the user experience.
+
 
 Drawbacks
 =========