docs #4138 Document sequence fields and email logging

Author: joemull

docs/md/sequence-fields.md

@@ -0,0 +1,11 @@
+# Sequence fields
+
+We use several patterns across Janeway to let users set the sequence of things, most commonly with a `PositiveIntegerField`.
+
+Because we sometimes expose this number to end users in form inputs, it is worth thinking about the usability of the default value. The number 1 is low enough to be easy for end users to manipulate. Zero is sometimes most convenient from a programming perspective, but avoid it if possible, since it can be counter-intuitive for non-programmers.
+
+```py
+sequence = models.PositiveIntegerField(default=1)
+```
+
+Of course, it is best if end users do not have to deal with this number at all. User interfaces should use accessible buttons that move things up or down in the sequence. This allows us to write an algorithm to check that multiple things have not been given the same sequence, and it keeps the user from having to recall off-screen information about the order of other items whilst performing an action.

docs/md/task-and-email-logs.md

@@ -0,0 +1,28 @@
+# Task and email logs
+
+Janeway creates a number of logs (`utils.LogEntry`) for actions that happen during the workflow. Many these actions trigger an email to be sent. The logging is thus managed by the email sending process. A log is created created that records the type of action taken in Janeway as well as details of the email.
+
+## The notification system
+
+The notification system, where emails and logs are created, lives in `src/utils`, and uses hooks to provide plugin functionality:
+
+```
+src/utils/notify.py
+src/utils/notify_helpers.py
+src/utils/notify_plugins/notify_email.py
+src/utils/notify_plugins/email_log.py
+src/utils/notify_plugins/notify_slack.py
+```
+
+<!--
+TODO
+  * Document how the notify plugins work, exactly
+  * Document when to use functions like send_email_with_body_from_user, etc.
+
+-->
+
+## Exceptions to action logging
+
+There are exceptions to logging that are worth noting:
+
+- Contact messages are not logged. Instead they are simply stored as objects.