Write some basic "dealing with Conduit changes" documentation

Summary:
Ref T9980. No magic here, just write a little bit about how to find outdated callers. Update the technical doc.

Also:

  - Fix an unrelated bug where you couldn't leave comments if an object had missing, required, custom fields.
  - Restore the ConduitConnectionLog table so `bin/storage adjust` doesn't complain.

Test Plan: Read docs.

Reviewers: chad

Reviewed By: chad

Maniphest Tasks: T9980

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

src/docs/tech/conduit.diviner

@@ -3,54 +3,26 @@
 
 Technical overview of the Conduit API.
 
-= Overview =
+Overview
+========
 
-Conduit is an informal mechanism for transferring ad-hoc JSON blobs around on
-the internet.
+Conduit is the HTTP API for Phabricator. It is roughly JSON-RPC: you usually
+pass a JSON blob, and usually get a JSON blob back, although both call and
+result formats are flexible in some cases.
 
-Theoretically, it provides an API to Phabricator so external scripts (including
-scripts written in other languages) can interface with the applications in the
-Phabricator suite. It technically does this, sort of, but it is unstable and
-incomplete so you should keep your expectations very low if you choose to build
-things on top of it.
+The easiest way to begin exploring Conduit is by visiting {nav Conduit} in the
+web UI. The application provides an API console which you can use to explore
+available methods, make calls, read documentation, and see examples.
 
-NOTE: Hopefully, this should improve over time, but making Conduit more robust
-isn't currently a major project priority because there isn't much demand for it
-outside of internal scripts. If you want to use Conduit to build things on top
-of Phabricator, let us know so we can adjust priorities.
+The API console has details about how to construct calls and generate API
+tokens for authentication.
 
-Conduit provides an authenticated HTTP API for Phabricator. It is informal and
-extremely simple: you post a JSON blob and you get a JSON blob back. You can
-access Conduit in PHP with @{class@libphutil:ConduitClient}, or in any language
-by executing `arc call-conduit method` (see `arc help call-conduit` for
-more information). You can see and test available methods at `/conduit/` in
-the web interface.
+The three primary ways to make Conduit calls are:
 
-Arcanist is implemented using Conduit, and @{class:PhabricatorBot} is
-intended as a practical example of how to write a program which interfaces with
-Phabricator over Conduit.
+  - `arc call-conduit`: You can use this `arc` command to execute low-level
+    Conduit calls.
+  - `curl`: You can format a call with basic HTTP parameters and cURL.
+  - `ConduitClient`:
 
-= Class Relationships =
-
-The primary Conduit workflow is exposed at `/api/`, which routes to
-@{class:PhabricatorConduitAPIController}. This controller builds a
-@{class:ConduitAPIRequest} representing authentication information and POST
-parameters, instantiates an appropriate subclass of @{class:ConduitAPIMethod},
-and passes the request to it. Subclasses of @{class:ConduitAPIMethod} implement
-the actual methods which Conduit exposes.
-
-Conduit calls which fail throw @{class:ConduitException}, which the controller
-handles.
-
-There is a web interface for viewing and testing Conduit called the "Conduit
-Console", implemented by @{class:PhabricatorConduitConsoleController} at
-`/conduit/`.
-
-A log of connections and calls is stored in
-@{class:PhabricatorConduitMethodCallLog}, and can be accessed on the web via
-@{class:PhabricatorConduitLogController} at `/conduit/log/`.
-
-Conduit provides a token-based handshake mechanism used by
-`arc install-certificate` at `/conduit/token/`, implemented by
-@{class:PhabricatorConduitTokenController} which stores generated tokens using
-@{class:PhabricatorConduitCertificateToken}.
+There are also clients available in other languages. The Arcanist CLI client
+for Phabricator is implemented over Conduit.