Improve docs for pcap open failures (#1380)

docs/Troubleshooting.md

@@ -20,6 +20,41 @@ before you [open an issue](#opening-an-issue).
 
 ## I've clicked to open a packet capture in Brim, but it failed to open
 
+There are two different broad categories of such problems, one involving the
+application configured to open packet capture files and the other involving
+the packet captures themselves. The sections below describe each category in
+detail.
+
+### Application problems
+
+To start debugging such problems, it helps to understand how Brim opens flows
+extracted from pcaps. Once the 5-tuple, connection start time, and connection
+duration are isolated from the Zeek `conn` record for the flow, the
+[`zqd`](https://github.com/brimsec/zq/tree/master/ppl/cmd/zqd) process uses an
+index to extract the packets for the target flow into a temporary file. Once
+this temporary file has been written to the local filesystem, the application
+on your operating system that's configured to automatically open files ending
+in `.pcap` will be launched to open this file.
+
+In typical environments, that application will be Wireshark. However, if no
+such application is installed or configured to open `.pcap` files, clicking the
+**Packets** button in Brim will have no effect. The lack of guidance in this
+ case is currently lacking on macOS and Linux
+([brim/1379](https://github.com/brimsec/brim/issues/1379)).
+
+To fix this problem, ensure Wireshark or a similar utility is installed
+and that you can open `.pcap` files outside of Brim by double-clicking them
+in the general "files" utility for your operating system.
+
+Note that it would be a misconfiguration to set Brim itself as your operating
+system's default application for opening `.pcap` files, as this would make
+Brim's **Packets** button "point at itself".
+
+### Packet capture problems
+
+If you are able to open a pcap file in Wireshark but not extract flows from it
+in Brim, it's likely a problem unique to the packet capture itself. 
+
 Unfortunately, not all packet captures are created equal. The library that
 Brim invokes to extract flows from your pcap handles the most common variations
 we've encountered, but you may have come across a corner case that it wasn't
@@ -46,16 +81,22 @@ First, if you don't see an error message in Brim, or the error seems terse and
 unhelpful, it may help us get to the bottom of it faster if you include the
 debug info from [Developer Tools](#developer-tools).
 
-Beyond that, the most comprehensive way to debug is to use the
-[zq](https://github.com/brimsec/zq) toolset at the command line to perform
-steps that are functionally equivalent to those initiated by the Brim
-application to extract flows from your pcap. This will allow you to better
-observe the individual steps so you can report the point at which you see a
-failure. This consists of the following steps:
+Beyond that, the most comprehensive way to debug is to use a tool at the
+command line to perform steps that are functionally equivalent to those
+initiated by the Brim application to extract flows from your pcap. This will
+allow you to better observe the individual steps so you can report the point at
+which you see a failure. This consists of the following steps:
+
+1. Locate the `pcap` utility that's bundled with Brim. This binary can be
+found in the following location on each platform:
+
+   |**OS Platform**|**Location**|
+   |---------------|------------|
+   | **Windows**   | `%USERPROFILE%\AppData\Local\Brim\app-<version>\resources\app\zdeps` |
+   | **macOS**     | `/Applications/Brim.app/Contents/Resources/app/zdeps` |
+   | **Linux**     | `/usr/lib/brim/resources/app/zdeps`                   |
+
 
-1. Install the zq toolset by following the
-[installation steps in the zq README](https://github.com/brimsec/zq/blob/master/README.md#installation).
-Ensure you can run the `pcap` executable, which is needed for this exercise.
    ```
    $ pcap
    NAME