Document the N+1 problem and DarkConsole

.divinerconfig

@@ -6,8 +6,8 @@
     "config" : "Configuration",
     "userguide" : "Application User Guides",
     "contrib" : "Contributing",
-    "flavortext" : "Flavor Text",
     "developer" : "Phabricator Developer Guides",
+    "flavortext" : "Flavor Text",
     "differential" : "Differential (Code Review)",
     "diffusion" : "Diffusion (Repository Browser)",
     "maniphest" : "Maniphest (Task Tracking)",

src/docs/developer/darkconsole.diviner

@@ -21,5 +21,43 @@ disabled by default (and **you should not enable it in production**). It has
 some simple safeguards to prevent leaking credential information but enabling it
 in production may compromise the integrity of an install.
 
-You enable DarkConsole in your configuration, by setting ##darkconsole.enabled**
-to ##true##.
+You enable DarkConsole in your configuration, by setting ##darkconsole.enabled##
+to ##true##, and then clicking the "Enable DarkConsole" link in the page footer.
+Once DarkConsole is enabled, you can show or hide it by pressing ##`## on your
+keyboard.
+
+Since the "Enable DarkConsole" link is not available to logged-out users (and
+stored as a per-user preference), you can also set ##darkconsole.always-on## if
+you need to access DarkConsole on logged-out pages.
+
+DarkConsole has a number of tabs, each of which is powered by a "plugin". You
+can use them to access different debugging and performance features.
+
+= Plugin: Error Log =
+
+The "Error Log" plugin shows errors that occurred while generating the page,
+similar to the httpd ##error.log##. You can send information to the error log
+explicitly with the @{function@libphutil:phlog} function.
+
+If errors occurred, a red dot will appear on the plugin tab.
+
+= Plugin: Request =
+
+The "Request" plugin shows information about the HTTP request the server
+received, and the server itself.
+
+= Plugin: Services =
+
+The "Services" plugin lists calls a page made to external services, like
+MySQL and the command line.
+
+= Plugin: XHProf =
+
+The "XHProf" plugin gives you access to the XHProf profiler. To use it, you need
+to install the corresponding PHP plugin -- see instructions in the
+@{article:Installation Guide}. Once it is installed, you can use XHProf to
+profile the runtime performance of a page.
+
+= Plugin: Config =
+
+The "Config" plugin shows active Phabricator configuration values.

src/docs/developer/n_plus_one.diviner

@@ -10,8 +10,8 @@ The N+1 query problem is a common performance antipattern. It looks like this:
   COUNTEREXAMPLE
   $cats = load_cats();
   foreach ($cats as $cat) {
-   $cats_hats = load_hats_for_cat($cat);
-   // ...
+    $cats_hats = load_hats_for_cat($cat);
+    // ...
   }
 
 Assuming ##load_cats()## has an implementation that boils down to:
@@ -49,7 +49,7 @@ iterating through it (this is oversimplified and omits error checking):
   $cats = load_cats();
   $hats = load_all_hats_for_these_cats($cats);
   foreach ($cats as $cat) {
-   $cats_hats = $hats[$cat->getID()];
+    $cats_hats = $hats[$cat->getID()];
   }
 
 That is, issue these queries:
@@ -60,7 +60,8 @@ That is, issue these queries:
 In this case, the total number of queries issued is always 2, no matter how many
 objects there are. You've removed the "N" part from the page's query plan, and
 are no longer paying the overhead of issuing hundreds of extra queries. This
-will perform much better.
+will perform much better (although, as with all performance changes, you should
+verify this claim by measuring it).
 
 = Detecting the Problem =
 
@@ -70,4 +71,4 @@ easiest way to detect this issue is to check the "Services" tab in DarkConsole
 page. If you see a bunch of similar queries, this often indicates an N+1 query
 issue (or a similar kind of query batching problem). Restructuring code so you
 can run a single query to fetch all the data at once will always improve the
-performance of the page.
+performance of the page.