Docs: rework troubleshooting/help page

Add guidance on how and where to get help.

docs/help.rst

@@ -0,0 +1,105 @@
+.. _help:
+
+Help
+====
+
+
+.. _troubleshooting:
+
+Troubleshooting
+---------------
+
+If Anymail's not behaving like you expect, these troubleshooting tips can
+often help you pinpoint the problem...
+
+**Check the error message**
+
+  Look for an Anymail error message in your console (running Django in dev mode)
+  or in your server error logs. If you see something like "invalid API key"
+  or "invalid email address", that's often a big first step toward being able
+  to solve the problem.
+
+**Check your ESPs API logs**
+
+  Most ESPs offer some sort of API activity log in their dashboards.
+  Check their logs to see if the
+  data you thought you were sending actually made it to your ESP, and
+  if they recorded any errors there.
+
+**Double-check common issues**
+
+  * Did you add any required settings for your ESP to the `ANYMAIL` dict in your
+    settings.py? (E.g., ``"SENDGRID_API_KEY"`` for SendGrid.) See :ref:`supported-esps`.
+  * Did you add ``'anymail'`` to the list of :setting:`INSTALLED_APPS` in settings.py?
+  * Are you using a valid from address? Django's default is "webmaster@localhost",
+    which most ESPs reject. Either specify the ``from_email`` explicitly on every message
+    you send, or add :setting:`DEFAULT_FROM_EMAIL` to your settings.py.
+
+**Try it without Anymail**
+
+  If you think Anymail might be causing the problem, try switching your
+  :setting:`EMAIL_BACKEND` setting to
+  Django's :ref:`File backend <django:topic-email-file-backend>` and then running your
+  email-sending code again. If that causes errors, you'll know the issue is somewhere
+  other than Anymail. And you can look through the :setting:`EMAIL_FILE_PATH`
+  file contents afterward to see if you're generating the email you want.
+
+
+.. _contact:
+.. _support:
+
+Support
+-------
+
+If you've gone through the troubleshooting above and still aren't sure what's wrong,
+the Anymail community is happy to help. Anymail is supported and maintained by the
+people who use it---like you! (The vast majority of Anymail contributors volunteer
+their time, and are not employees of any ESP.)
+
+Here's how to contact the Anymail community:
+
+**"How do I...?"**
+
+  If the *Search docs* box on the left doesn't find an answer,
+  ask a `question on Stack Overflow`_ and tag it "django-anymail".
+
+**"I'm getting an error or unexpected behavior..."**
+
+  Either ask a `question on Stack Overflow`_ tagged "django-anymail"
+  or open a `GitHub issue`_. (But please don't raise the same issue
+  in both places.)
+
+  Be sure to include:
+
+  * which ESP you're using (Mailgun, SendGrid, etc.)
+  * what versions of Anymail, Django, and Python you're running
+  * the relevant portions of your code and settings
+  * the text of any error messages
+  * any exception stack traces
+
+  and any other info you obtained from :ref:`troubleshooting <troubleshooting>`,
+  such as what you found in your ESP's activity log.
+
+**"I found a bug..."**
+
+  Open a `GitHub issue`_. Be sure to include the information listed above.
+  (And if you know what the problem is, we always welcome
+  :ref:`contributions <contributing>` with a fix!)
+
+**"I found a security issue!"**
+
+  Contact the Anymail maintainers by emailing *security<AT>anymail<DOT>info.*
+  (Please don't open a GitHub issue or post publicly about potential security problems.)
+
+**"Could Anymail support this ESP or feature...?"**
+
+  If there's already a `GitHub issue`_ open, express your support using GitHub's
+  `thumbs up reaction`_. If not, open a new issue. Either way, be sure to add a comment
+  if you're able to help with development or testing.
+
+
+.. _GitHub issue: https://github.com/anymail/django-anymail/issues
+.. _question on Stack Overflow:
+    https://stackoverflow.com/questions/ask?tags=django-anymail
+.. _thumbs up reaction:
+    https://blog.github.com/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/

docs/index.rst

@@ -25,7 +25,7 @@ Documentation
    inbound
    esps/index
    tips/index
-   troubleshooting
+   help
 
 .. toctree::
    :maxdepth: 2

docs/troubleshooting.rst

@@ -1,60 +0,0 @@
-.. _troubleshooting:
-
-Troubleshooting
-===============
-
-Anymail throwing errors? Not sending what you want? Here are some tips...
-
-
-Figuring out what's wrong
--------------------------
-
-**Check the error message**
-
-  Look for an Anymail error message in your
-  web browser or console (running Django in dev mode) or in your server
-  error logs. If you see something like "invalid API key"
-  or "invalid email address", that's probably 90% of what you'll need to know
-  to solve the problem.
-
-**Check your ESPs API logs**
-
-  Most ESPs offer some sort of API activity log in their dashboards.
-  Check the logs to see if the
-  data you thought you were sending actually made it to your ESP, and
-  if they recorded any errors there.
-
-**Double-check common issues**
-
-  * Did you add any required settings for your ESP to your settings.py?
-    (E.g., `ANYMAIL_SENDGRID_API_KEY` for SendGrid.) See :ref:`supported-esps`.
-  * Did you add ``'anymail'`` to the list of :setting:`INSTALLED_APPS` in settings.py?
-  * Are you using a valid from address? Django's default is "webmaster@localhost",
-    which won't cut it. Either specify the ``from_email`` explicitly on every message
-    you send through Anymail, or add :setting:`DEFAULT_FROM_EMAIL` to your settings.py.
-
-**Try it without Anymail**
-
-  Try switching your :setting:`EMAIL_BACKEND` setting to
-  Django's :ref:`File backend <django:topic-email-file-backend>` and then running your
-  email-sending code again. If that causes errors, you'll know the issue is somewhere
-  other than Anymail. And you can look through the :setting:`EMAIL_FILE_PATH`
-  file contents afterward to see if you're generating the email you want.
-
-
-Getting help
-------------
-
-If you've gone through the suggestions above and still aren't sure what's wrong,
-the Anymail community is happy to help. Anymail is supported and maintained by the
-people who use it -- like you! (We're not employees of any ESP.)
-
-For questions or problems with Anymail, you can open a `GitHub issue`_.
-(And if you've found a bug, you're welcome to :ref:`contribute <contributing>` a fix!)
-
-Whenever you open an issue, it's always helpful to mention which ESP you're using,
-include the relevant portions of your code and settings, the text of any error messages,
-and any exception stack traces.
-
-
-.. _GitHub issue: https://github.com/anymail/django-anymail/issues