Add documentation for the Owners tool

Summary:
As title.

Please help me to improve the wording!

Test Plan:
generate the documentation from the diviner file; read it; spell
check

Reviewers: epriestley, nh

Reviewed By: nh

CC: aran, dihde14, mpodobnik, prithvi, TomL, epriestley

Differential Revision: https://secure.phabricator.com/D1395

src/applications/owners/controller/base/PhabricatorOwnersController.php

@@ -39,6 +39,16 @@ abstract class PhabricatorOwnersController extends PhabricatorController {
     $nav->appendChild($view);
     $page->appendChild($nav);
 
+    $doclink =
+      PhabricatorEnv::getDoclink('article/Owners_Tool_User_Guide.html');
+    $tabs = array(
+      'help' => array(
+        'href' => $doclink,
+        'name' => 'Help',
+      ),
+    );
+    $page->setTabs($tabs, null);
+
     $response = new AphrontWebpageResponse();
     return $response->setContent($page->render());
   }

src/applications/owners/controller/base/__init__.php

@@ -8,6 +8,7 @@
 
 phutil_require_module('phabricator', 'aphront/response/webpage');
 phutil_require_module('phabricator', 'applications/base/controller/base');
+phutil_require_module('phabricator', 'infrastructure/env');
 phutil_require_module('phabricator', 'view/layout/sidenavfilter');
 
 phutil_require_module('phutil', 'parser/uri');

src/applications/owners/controller/edit/PhabricatorOwnersEditController.php

@@ -219,6 +219,10 @@ class PhabricatorOwnersEditController extends PhabricatorOwnersController {
         id(new AphrontFormSelectControl())
           ->setName('auditing')
           ->setLabel('Auditing')
+          ->setCaption('With auditing enabled, all future commits that touch '.
+                       'this package will be reviewed to make sure an owner '.
+                       'of the package is involved and the commit message has '.
+                       'a valid revision, reviewed by, and author.')
           ->setOptions(array(
             'disabled'  => 'Disabled',
             'enabled'   => 'Enabled',

src/docs/userguide/owners.diviner

@@ -0,0 +1,30 @@
+@title Owners Tool User Guide
+@group userguide
+
+Use Owners to define and/or monitor code you care about.
+
+= Packages =
+
+Owners tool allows you to define a code package by specifying a group of paths.
+The package can then be used to monitor the paths. For example, it can be used
+in Herald rules and in the "Related Commits" feature (see below).
+
+= Related Commits =
+
+Once the package is defined, all future commits touching any path defined in
+the package will be recorded as "Related Commits" of the package.
+
+= Commits Needing Attention =
+
+Owners tool enables the owners of the package to monitor the commits that might
+need attention. If "auditing" is enabled for a package, a related commit will
+be marked as "Needing Attention" if
+
+  - it's neither authored nor reviewed by an owner of the package,
+  - no revision found for the commit,
+  - the commit author is not recognized, or
+  - the author or the reviewer specified in the commits don't match the ones in
+  the Differential revision
+
+The owners of the package can accept or specify concern for such commits by
+clicking the "Audit Status" link.