Improve arcanist documentation

Summary:
There's some good feedback from Wikimedia here:

http://lists.wikimedia.org/pipermail/wikitech-l/2012-August/062252.html

Try to improve on some of it. In particular:

  - Make it clear that /arcanist/ is not where you should be (D3235).
  - Provide better connections from "Arcanist User Guide" to other documents.
  - Provide a "Quick Start" guide with a simpler set of instructions that links to richer documentation.
  - Reorganize the project setup guide to put more important things earlier on.
  - Make it clear that you should commit `.arcconfig`.
  - Provide more hints for initial setup.
  - Describe and organize advanced configuration/extension documentation as more clearly separate from basic setup/install documentation.

Test Plan: Generated, read docs.

Reviewers: vrana, btrahan

Reviewed By: vrana

CC: aran

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

src/docs/userguide/arcanist.diviner

@@ -9,11 +9,18 @@ unit tests, and manages common workflows like getting changes into Differential
 for review.
 
 A detailed command reference is available by running ##arc help##. This
-document provides a high level overview of common workflows.
+document provides an overview of common workflows and installation.
 
 Arcanist has technical, contributor-focused documentation here:
 <http://www.phabricator.com/docs/arcanist/>
 
+= Quick Start =
+
+A quick start guide is available at @{article:Arcanist Quick Start}. It provides
+a much more compact summary of how to get `arc` set up and running for a new
+project. You may want to start there, and return here if you need more
+information.
+
 = Overview =
 
 Arcanist is a wrapper script that sits on top of other tools (e.g.,
@@ -21,10 +28,19 @@ Differential, linters, unit test frameworks, git, Mercurial, and SVN) and
 provides a simple command-line API to manage code review and some related
 revision control operations.
 
+For a detailed list of all available commands, run:
+
+  $ arc help
+
+For detailed information about a specific command, run:
+
+  $ arc help <command>
+
 Arcanist allows you to do things like:
 
   - get detailed help about available commands with ##arc help##
-  - send your code to Differential for review with ##arc diff##
+  - send your code to Differential for review with ##arc diff## (for detailed
+    instructions, see @{article:Arcanist User Guide: arc diff})
   - show pending revision information with ##arc list##
   - find likely reviewers for a change with ##arc cover##
   - apply changes in a revision to the working copy with ##arc patch##
@@ -37,6 +53,7 @@ Arcanist allows you to do things like:
 Once you've configured lint and unit test integration, you can also:
 
   - check your code for syntax and style errors with ##arc lint##
+    (see @{article:Arcanist User Guide: Lint})
   - run unit tests that cover your changes with ##arc unit##
 
 Arcanist integrates with other tools:
@@ -60,7 +77,8 @@ SVN repositories.
 = Installing Arcanist =
 
 Arcanist is meant to be installed on your local machine or development server --
-whatever machine you're editing code on. It runs on Linux, Mac OS X, and
+whatever machine you're editing code on. It runs on Linux,
+Mac OS X (see @{article:Arcanist User Guide: Mac OS X}), and
 Windows (see @{article:Arcanist User Guide: Windows}).
 
 Arcanist is written in PHP, so you need to install the PHP CLI first if you
@@ -96,9 +114,9 @@ You can later upgrade Arcanist and libphutil to the latest versions with
 
 == Installing Arcanist for a Team ==
 
-Arcanist changes quickly and doesn't currently have an auto-update mechanism,
+Arcanist changes quickly, so it can be something of a headache to get it
-so it can be something of a headache to get it installed and keep people up to
+installed and keep people up to date. Here are some approaches you might be
-date. Here are some approaches you might be able to use:
+able to use:
 
   - Facebook does most development on development servers, which have a standard
     environment and NFS mounts. Arcanist and libphutil themselves live on an
@@ -125,5 +143,18 @@ to your ##.bashrc##, ##.profile## or similar:
 
 Continue by:
 
+  - setting up a new project for use with `arc`, with
+    @{article:Arcanist User Guide: Configuring a New Project}; or
   - learning how to use `arc` to send changes for review with
     @{article:Arcanist User Guide: arc diff}.
+
+Advanced topics are also available. These are detailed guides to configuring
+technical features of `arc` that refine its behavior. You do not need to read
+them to get it working.
+
+ - @{article:Arcanist User Guide: Commit Ranges}
+ - @{article:Arcanist User Guide: Lint}
+ - @{article:Arcanist User Guide: Customizing Existing Linters}
+ - @{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows}
+ - @{article:Arcanist User Guide: Code Coverage}
+ - @{article:Arcanist User Guide: Repository Hooks}

src/docs/userguide/arcanist_commit_ranges.diviner

@@ -3,6 +3,10 @@
 
 Explains how commit ranges work in Arcanist.
 
+This is an advanced user guide which covers a complicated topic in detail. If
+you're just getting started, you don't need to look at this yet. Instead, start
+with the @{article:Arcanist User Guide}.
+
 = Overview =
 
 //In Subversion, `arc` commands always operate on the uncommitted changes in the

src/docs/userguide/arcanist_coverage.diviner

@@ -3,6 +3,15 @@
 
 Explains code coverage features in Arcanist and Phabricator.
 
+This is a configuration guide that helps you set up advanced features. If you're
+just getting started, you don't need to look at this yet. Instead, start with
+the @{article:Arcanist User Guide}.
+
+Before you can configure coverage features, you must set up unit test
+integration. For instructions, see @{article:Arcanist User Guide: Configuring
+a New Project} and @{article:Arcanist User Guide: Customizing
+Lint, Unit Tests and Workflows}.
+
 = Using Coverage Features =
 
 If your project has unit tests with coverage integration (see below for

src/docs/userguide/arcanist_diff.diviner

@@ -1,17 +1,17 @@
 @title Arcanist User Guide: arc diff
 @group userguide
 
-Guide to running `arc diff`.
+Guide to running `arc diff`, to send changes to Differential for review.
-
-= Overview =
 
 This article assumes you have `arc` installed and running; if not, see
 @{article:Arcanist User Guide} for help getting it set up.
 
-This document is intended for users of `arc diff`, and is a practical
+Before running `arc diff`, you should create a `.arcconfig` file. If someone
-guide to using it to send changes for review. If you are installing and
+set things up for you, they may already have done this. See
-configuring Phabricator, make sure to read the more comprehensive information in
+@{article:Arcanist User Guide: Configuring a New Project} for instructions and
-@{article:Arcanist User Guide: Configuring a New Project}.
+information.
+
+= Overview =
 
 While `arc` has a large number of commands that interface with various
 Phabricator applications, the primary use of `arc` is to send changes for

src/docs/userguide/arcanist_extending_lint.diviner

@@ -3,6 +3,14 @@
 
 Explains how to customize existing linters.
 
+This is a configuration guide that helps you set up advanced features. If you're
+just getting started, you don't need to look at this yet. Instead, start with
+the @{article:Arcanist User Guide}.
+
+This guide explains how to refine lint behavior. To configure lint in the first
+place, see @{article:Arcanist User Guide: Configuring a New Project} and
+@{article:Arcanist User Guide: Lint}.
+
 = Overview =
 
 Arcanist ships with a number of linters which you may want to reuse in whole

src/docs/userguide/arcanist_lint.diviner

@@ -3,6 +3,14 @@
 
 Guide to lint, linters, and linter configuration.
 
+This is a configuration guide that helps you set up advanced features. If you're
+just getting started, you don't need to look at this yet. Instead, start with
+the @{article:Arcanist User Guide}.
+
+This guide explains how lint works when configured in an `arc` project. If
+you haven't set up a project yet, do that first. For instructions, see
+@{article:Arcanist User Guide: Configuring a New Project}.
+
 = Overview =
 
 "Lint" refers to a general class of programming tools which analyze source code

src/docs/userguide/arcanist_lint_unit.diviner

@@ -3,6 +3,10 @@
 
 Explains how to build new classes to control how Arcanist behaves.
 
+This is a configuration guide that helps you set up advanced features. If you're
+just getting started, you don't need to look at this yet. Instead, start with
+the @{article:Arcanist User Guide}.
+
 = Overview =
 
 Arcanist has some basic configuration options available in the `.arcconfig`

src/docs/userguide/arcanist_mac_os_x.diviner

@@ -24,3 +24,8 @@ You can edit your `~/.profile` to permanently configure environmental variables.
 
 Now you should be able to run `arc` like a normal command.
 
+= Next Steps =
+
+Continue by:
+
+  - returning to @{article:Arcanist User Guide}.

src/docs/userguide/arcanist_new_project.diviner

@@ -1,62 +1,20 @@
 @title Arcanist User Guide: Configuring a New Project
 @group userguide
 
-Explains how to configure Arcanist projects with ##.arcconfig## files.
+Explains how to configure Arcanist projects with `.arcconfig` files.
-
-= Overview =
-
-You can run `arc` commands that require a working copy in any Git, Subversion
-or Mercurial working copy, but some features won't work unless you set up an
-`.arcconfig` file to configure settings for the project. Creating this file is
-easy and only takes a few minutes.
-
-Without `.arcconfig`:
-
-  - You will need to set a default Phabricator URI with
-    `arc set-config default <uri>`, or specify an explicit URI
-    with `--conduit-uri` each time you run a command.
-  - You will not be able to run linters through arc unless you pass `--engine`
-    explicitly.
-  - You will not be able to customize certain linter parameters even with
-    `--engine`.
-  - You will not be able to run unit tests through arc unless you pass
-    `--engine` explicitly.
-  - You will not be able to trigger lint and unit integration through
-    `arc diff`.
-  - You will not be able to put Git working copies into immutable history mode
-    (see below).
-  - You will not be able to specify a repository encoding. UTF-8 will be assumed
-    if you do not pass `--encoding`.
-  - You will not be able to add plugins to arc to modify existing workflows or
-    add new ones.
-  - You will not be able to load additional libraries unless you specify them
-    explicitly with `--load-phutil-library`.
-  - Symbol index integration, which allows users to click function or class
-    names in Differential and jump to their definitions, will not work.
-  - `arc patch` will be unable to detect that you are applying changes to the
-    wrong project.
-  - In Subversion, `arc` will be unable to determine the canonical root
-    of a project, and will assume it is the working directory (in Subversion
-    prior to 1.7) or the root of the checkout (in Subversion after 1.7). This
-    means the paths of files in diffs won't be anchored to the same place,
-    and will have different amounts of path context, which may be confusing for
-    reviewers and will sometimes prevent patches from applying properly if they
-    are applied against a different directory than they were generated from.
-  - In Subversion, `arc` will be unable to guess that you intend to update
-    an existing revision; you must use `--update` explicitly or `--preview`
-    and attach diffs via the web interface.
 
 = .arcconfig Basics =
 
+An ##.arcconfig## file is a JSON file which you check into your project's root.
+
 Arcanist uses ##.arcconfig## files to determine a number of things about project
-configuration. For instance, these are things it figures out from
+configuration. For instance, these are some of the things it figures out from
 ##.arcconfig##:
 
   - where the logical root directory of a project is;
   - which server Arcanist should send diffs to for code review; and
   - which lint rules should be applied.
 
-An ##.arcconfig## file is a JSON file which you check into your project's root.
 A simple, valid file looks something like this:
 
   {
@@ -72,6 +30,9 @@ Here's what these options mean:
 
 For an exhaustive list of available options, see below.
 
+NOTE: You should commit your `.arcconfig` file! It contains project
+configuration, not user configuration.
+
 = Advanced .arcconfig =
 
 Other options include:
@@ -193,3 +154,50 @@ The general intent here is:
     next to other repositories.
   - Or put everything in some standard location and add it to `include_path`.
 
+= Running Without .arcconfig =
+
+Although you don't need to set up `.arcconfig`, and you can run `arc` command
+that require a working copy in any Git, Subversion or Mercurial working copy,
+some features won't work unless you set up an `.arcconfig` file.
+
+Without `.arcconfig`:
+
+  - You will need to set a default Phabricator URI with
+    `arc set-config default <uri>`, or specify an explicit URI
+    with `--conduit-uri` each time you run a command.
+  - You will not be able to run linters through arc unless you pass `--engine`
+    explicitly.
+  - You will not be able to customize certain linter parameters even with
+    `--engine`.
+  - You will not be able to run unit tests through arc unless you pass
+    `--engine` explicitly.
+  - You will not be able to trigger lint and unit integration through
+    `arc diff`.
+  - You will not be able to put Git working copies into immutable history mode
+    (see below).
+  - You will not be able to specify a repository encoding. UTF-8 will be assumed
+    if you do not pass `--encoding`.
+  - You will not be able to add plugins to arc to modify existing workflows or
+    add new ones.
+  - You will not be able to load additional libraries unless you specify them
+    explicitly with `--load-phutil-library`.
+  - Symbol index integration, which allows users to click function or class
+    names in Differential and jump to their definitions, will not work.
+  - `arc patch` will be unable to detect that you are applying changes to the
+    wrong project.
+  - In Subversion, `arc` will be unable to determine the canonical root
+    of a project, and will assume it is the working directory (in Subversion
+    prior to 1.7) or the root of the checkout (in Subversion after 1.7). This
+    means the paths of files in diffs won't be anchored to the same place,
+    and will have different amounts of path context, which may be confusing for
+    reviewers and will sometimes prevent patches from applying properly if they
+    are applied against a different directory than they were generated from.
+  - In Subversion, `arc` will be unable to guess that you intend to update
+    an existing revision; you must use `--update` explicitly or `--preview`
+    and attach diffs via the web interface.
+
+= Next Steps =
+
+Continue by:
+
+  - returning to @{article:Arcanist User Guide}.

src/docs/userguide/arcanist_quick_start.diviner

@@ -0,0 +1,100 @@
+@title Arcanist Quick Start
+@group userguide
+
+Quick guide to getting Arcanist working for a new project.
+
+This is a summary of steps to install Arcanist, configure a project for use with
+it, and run `arc` to send changes for review.
+
+= Install Arcanist =
+
+For detailed instructions on installing Arcanist, see
+@{article:Arcanist User Guide}.
+
+  - For Mac OS X, see @{article:Arcanist User Guide: Mac OS X}.
+  - For Windows, see @{article:Arcanist User Guide: Windows}.
+
+First, install dependencies:
+
+  - Install PHP.
+  - Install Git.
+
+Then install Arcanist itself:
+
+  $ mkdir somewhere/
+  $ cd somewhere/
+  somewhere/ $ git clone git://github.com/facebook/libphutil.git
+  somewhere/ $ git clone git://github.com/facebook/arcanist.git
+
+Add `arc` to your path:
+
+  $ export PATH="$PATH:/somewhere/arcanist/bin/"
+
+This won't work for Windows, see @{article:Arcanist User Guide: Windows} for
+instructions.
+
+= Configure Your Project =
+
+For detailed instructions on project configuration, see
+@{article:Arcanist User Guide: Configuring a New Project}.
+
+Create a `.arcconfig` file in your project's working copy:
+
+  $ cd yourproject/
+  yourproject/ $ $EDITOR .arcconfig
+  yourproject/ $ cat .arcconfig
+  {
+    "project_id" : "yourprojectname",
+    "conduit_uri" : "https://phabricator.example.com/"
+  }
+
+Set `project_id` to a string that identifies the project.
+
+Set `conduit_uri` to the URI for your Phabricator install (where `arc`
+should send changes to).
+
+NOTE: You should **commit this file** to the repository.
+
+= Install Arcanist Credentials =
+
+Credentials allow you to authenticate. You must have an account on Phabricator
+before you can perform this step.
+
+  $ cd yourproject/
+  yourproject/ $ arc install-certificate
+  ...
+
+Follow the instructions. This will link your user account on your local machine
+to your Phabricator account.
+
+= Send Changes For Review =
+
+For detailed instructions on using `arc diff`, see
+@{article:Arcanist User Guide: arc diff}.
+
+Subversion:
+
+  $ $EDITOR file.c
+  $ arc diff
+
+Git:
+
+  $ $EDITOR file.c
+  $ git commit -a -m '...'
+  $ arc diff HEAD^
+
+Mercurial:
+
+  $ $EDITOR file.c
+  $ hg commit -m '...'
+  $ arc diff tip^
+
+= Next Steps =
+
+Continue by:
+
+  - learning more about project configuration with
+    @{article:Arcanist User Guide: Configuring a New Project}; or
+  - learning more about `arc diff` with
+    @{article:Arcanist User Guide: arc diff}; or
+  - returning to @{article:Arcanist User Guide}.

src/docs/userguide/arcanist_windows.diviner

@@ -77,3 +77,8 @@ And this for GitPad (you may need to adjust the path):
   name=GitPad
   $ arc set-config editor "\"C:\Users\yourusername\AppData\Roaming\GitPad\GitPad.exe\""
 
+= Next Steps =
+
+Continue by:
+
+  - returning to @{article:Arcanist User Guide}.