Merge pull request RobotLocomotion#8520 from EricCousineau-TRI/featur…

…e/stackoverflow_tag

doc: Add `Getting Help` section

doc/developers.rst

@@ -8,6 +8,8 @@ For Developers
    :depth: 3
    :local:
 
+.. _pull_request:
+
 Introduction
 ============
 
@@ -98,6 +100,14 @@ The binary releases of Drake are built with GCC 5.4 on Ubuntu 16.04 and Apple Cl
 
 The links for these packages are listed in :ref:`binary-installation`.
 
+Issue Tracking
+==============
+
+.. toctree::
+    :maxdepth: 1
+
+    issues
+
 Code Review
 ===========
 
@@ -185,6 +195,42 @@ Review Process Tooling
 
 .. _continuous_integration_notes:
 
+User Assistance
+===============
+
+The user-facing instructions for requesting assistance are located in
+:ref:`getting_help`. The two main options for requesting assistance are either
+posting a GitHub issue or a StackOverflow question.
+
+Handling User GitHub Issues
+---------------------------
+
+See :ref:`issues`.
+
+If a GitHub issue should instead be a StackOverflow question (e.g. it is of a
+tutorial nature that does not require code or documentation modification),
+please request that the user repost the question on StackOverflow, post the
+new link on the GitHub issue, and close the issue.
+
+Handling User StackOverflow Questions
+-------------------------------------
+
+Please subscribe to the ``drake`` tag by following
+`these general instructions <https://meta.stackoverflow.com/a/336515/7829525>`_,
+if you are able to.
+
+Please also monitor for `unanswered StackOverflow posts
+<https://stackoverflow.com/unanswered/tagged/drake?tab=noanswers>`_
+once per day. If there are unanswered questions that you are unsure of the
+answer, consider posting on the Slack ``#onramp`` channel to see if someone
+can can look into the question.
+
+The following developers are subscribed to the ``drake`` tag, and will monitor
+it:
+
+  - Russ Tedrake
+  - Eric Cousineau
+
 Continuous Integration Notes
 ============================
 .. toctree::

doc/faq.rst

@@ -4,6 +4,11 @@
 Frequently Asked Questions
 **************************
 
+..warning::
+
+    This page is old. Please review :ref:`getting_help` for more up-to-date
+    information.
+
 .. contents:: `Table of contents`
    :depth: 3
    :local:

doc/getting_help.rst

@@ -0,0 +1,53 @@
+.. _getting_help:
+
+************
+Getting Help
+************
+
+Searching For Your Question
+===========================
+
+If you need help with Drake, please first review the documentation on this
+website for things such as :ref:`installation <installation_and_quick_start>`,
+`the C++ API <doxygen_cxx/index.html#://>`_, or
+:ref:`Python bindings <python-bindings>`.
+
+Please also briefly review
+`Drake's open and closed GitHub issues <https://github.com/RobotLocomotion/drake/issues?q=is%3Aissue>`_
+and `StackOverflow posts tagged for Drake <https://stackoverflow.com/questions/tagged/drake>`_
+to see if your issue has been encountered by someone else before.
+
+Asking Your Question
+====================
+
+If you know your question is a bug or feature request, please
+`post a GitHub issue <https://github.com/RobotLocomotion/drake/issues/new>`_.
+
+Otherwise, if you are seeking assistance (e.g. tutorials or a brief example),
+please `post a question on StackOverflow
+<https://stackoverflow.com/questions/ask?tags=drake>`_ with the ``drake`` tag.
+
+If you are actively developing with Drake and may need more active discussions
+than what StackOverflow and GitHub may offer, consider asking for access to the
+Drake Developers Slack Channel. To do so, please email Russ Tedrake for access.
+Please note that this access may not always be readily granted.
+
+If you wish to contribute a patch, please see how to :ref:`submit a pull request
+<pull_request>`.
+
+Older Sources
+=============
+
+Some information was previously on the
+:ref:`faq`
+page and a
+`mailing list <http://mailman.mit.edu/mailman/listinfo/drake-users>`_.
+Please do not use these resources, as they are now inactive.
+
+.. toctree::
+  :hidden:
+
+  faq
+
+..
+    Use a hidden toctree to suppress error about FAQ not being linked.

doc/index.rst

@@ -88,7 +88,8 @@ Here is a quick summary of capabilities:
 
 Most of these models/tools are described in `the companion textbook from an MIT course/MOOC <https://people.csail.mit.edu/russt/underactuated/underactuated.html?chapter=drake>`_.  We've also recently started populating the :doc:`gallery` (contributions welcome!).
 
-We hope you find this tool useful.   Please engage us `via github issues <https://github.com/RobotLocomotion/drake/issues>`_ with comments, questions, success stories, and frustrations.  And please contribute your best bug fixes, features, and examples!
+We hope you find this tool useful.  Please see :ref:`getting_help` if you wish
+to share your comments, questions, success stories, or frustrations.  And please contribute your best bug fixes, features, and examples!
 
 
 ************
@@ -122,13 +123,11 @@ Next steps
    :maxdepth: 1
 
    installation
-   developers
+   getting_help
    Doxygen (C++) <doxygen_cxx/index.html#://>
-   faq
-   issues
-   Mailing list <http://mailman.mit.edu/mailman/listinfo/drake-users>
-   credits
    GitHub <https://github.com/RobotLocomotion/drake>
+   developers
+   credits
 
 
 ********************************************

doc/issues.rst

@@ -1,3 +1,5 @@
+.. _issues:
+
 ***********************
 GitHub Issue Management
 ***********************
@@ -17,6 +19,14 @@ Please only assign labels if you are reasonably confident they are correct.
 The Drake development team will apply appropriate labels to issues during
 the weekly scrub.
 
+Owner
+=====
+
+All GitHub issues should have an owner. The Platform Reviewer should check once
+per day that `all unassigned issues
+<https://github.com/RobotLocomotion/drake/issues?q=is%3Aissue+is%3Aopen+no%3Aassignee>`_
+have an appropriate owner.
+
 Team
 ====
 Every issue must have at least one ``team`` label. If no team agrees to own an

doc/serve_sphinx.py

@@ -5,6 +5,7 @@
   $ bazel run //doc:serve_sphinx
 """
 
+import argparse
 import os
 import subprocess
 import sys
@@ -13,6 +14,19 @@
 from SimpleHTTPServer import SimpleHTTPRequestHandler
 from SocketServer import TCPServer
 
+
+def str2bool(value):
+    # From: https://stackoverflow.com/a/19233287/7829525
+    return value.lower() in ("yes", "y", "true", "t", "1")
+
+
+parser = argparse.ArgumentParser()
+parser.register('type', 'bool', str2bool)
+parser.add_argument(
+    "--browser", type='bool', default=True, metavar='BOOL',
+    help="Open browser. Disable this if you are frequently recompiling.")
+args = parser.parse_args()
+
 # Unpack zipfile and chdir into it.
 with zipfile.ZipFile("doc/sphinx.zip", "r") as archive:
     archive.extractall("sphinx-tmp")
@@ -41,11 +55,14 @@ def log_request(*_):
 print >>sys.stderr
 
 # Try the default browser, then wait.
-print >>sys.stderr, "Opening webbrowser and waiting ... use Ctrl-C to exit."
-if sys.platform == "darwin":
-    # macOS
-    webbrowser.open(http_url)
-else:
-    # Ubuntu
-    webbrowser.open("./index.html")
+if args.browser:
+    print >>sys.stderr, "Opening webbrowser"
+    if sys.platform == "darwin":
+        # macOS
+        webbrowser.open(http_url)
+    else:
+        # Ubuntu
+        webbrowser.open("./index.html")
+
+print >>sys.stderr, "Serving and waiting ... use Ctrl-C to exit."
 httpd.serve_forever()