Reorganized docs

architecture/lookups.rst

@@ -36,6 +36,34 @@ Ordering
 --------
 
 Ordering of entries in the Broken Hosts Lookup is important, but the Broken Hosts App ships with
-a saved search that will re-order the lookup table in a logical way.
+a saved search that will re-order the lookup table in a logical way. As a result of several years
+analyzing expected behavior across our customers, we've determined that the following order is as
+follows:
 
-Lorem ipsum ...
+1. Entries where index=\* AND sourcetype=\* AND alerting is temporarily suppressed
+2. Entries where sourcetype=\* AND alerting is temporarily suppressed
+3. Entries where index=\* AND alerting is temporarily suppressed
+4. Entries where host=\* AND alerting is temporarily suppressed
+5. Entries where index=\* AND host=\* AND alerting is temporarily suppressed
+6. Entries where sourcetype=\* AND host=\* AND alerting is temporarily suppressed
+7. Entries where alerting is temporarily suppressed
+8. Entries where index=\* AND sourcetype=\* AND alerting is permanently suppressed
+9. Entries where lateSecs is temporarily modified
+10. Entries where sourcetype=\* AND lateSecs is temporarily modified
+11. Entries where index=\* AND lateSecs is temporarily modified
+12. Entries where host=\* AND lateSecs is temporarily modified
+13. Entries where index=\* AND sourcetype=\* AND lateSecs is temporarily modified
+14. Entries where index=\* AND host=\* AND lateSecs is temporarily modified
+15. Entries where sourcetype=\* AND host=\* AND lateSecs is temporarily modified
+16. Entries where alerting is permanently suppressed
+17. Entries where lateSecs is permanently modified, or host=\* AND alerting is permanently
+    suppressed, or host=\* AND lateSecs is permanently modified, or sourcetype=\* AND host=\* AND
+    alerting is permanently suppressed
+18. Entries where index=\* AND host=\* AND alerting is permanently suppressed
+19. Entries where sourcetype=\* AND alerting is permanently suppressed
+20. Entries where index=\* AND alerting is permanently suppressed
+21. Entries where sourcetype=\* AND lateSecs is permanently modified
+22. Entries where index=\* AND lateSecs is permanently modified
+23. Entries where index=\* AND sourcetype=\* AND lateSecs is permanently modified
+24. Entries where index=\* AND host=\* AND lateSecs is permanently modified
+25. Entries where sourcetype=\* AND host=\* AND lateSecs is permanently modified

architecture/searches.rst

@@ -9,12 +9,20 @@ bh_stats_gen
 The ``bh_stats_gen`` search is responsible for generating statistics about data coming into Splunk.
 The results are written to the ``summary`` index, to be picked up and read by other searches for
 alerting purposes. It can be fine-tuned using the ``bh_stats_gen_contraints`` and
-``bh_stats_gen_additions`` macros
+``bh_stats_gen_additions`` macros.
 
 Broken Hosts - Auto Sort
 ------------------------
 
-Lorem ipsum ...
+The ``Broken Hosts - Auto Sort`` search was implemented in order to optimize the ordering of the
+Broken Hosts Lookup. Because the lookup is evaluated in a first-match fashion, the ordering of the
+lookup is critical to preventing incorrect matches. You can view more information about the
+ordering of the lookup in the :ref:`searches` documentation.
+
+This search modifies the Broken Hosts Lookup in the following ways:
+
+1. Entries are reordered based on the ordering rules defined in the :ref:`searches` documentation.
+2. All fields are converted to lower case, as the lookup is case insensitive.
 
 Broken Hosts Alert Search
 -------------------------

usage/configuration.rst

@@ -20,11 +20,6 @@ altogether depending on your requirements. If you're new to Broken Hosts, we sug
 of Broken Hosts and want to continue getting the alerts you're used to, you can use ``Broken Hosts
 Alert - by contact``.
 
-Adjusting the Broken Hosts Lookup
----------------------------------
-
-Lorem upsum ...
-
 Modifying the macros
 --------------------