tweaks to docs, targeting the desired behavior that isn't there yet

bin/pt-diskstats

@@ -3565,8 +3565,7 @@ The average number of megabytes read per second.
 =item rd_io_s
 
 The average number of IO reads per second.  This is the number that is actually
-sent to the physical device after merging adjacent requests and any other
-processing in the queue.
+sent to the physical device after merging adjacent requests in the queue.
 
 =item rd_mrg
 
@@ -3602,15 +3601,16 @@ indicator of how loaded the device really is.
 =item in_prg
 
 The number of requests that were in progress.  Unlike the read and write
-concurrencies, which are averages that are generated from reliable numbers,
-this number is an instantaneous sample, and you can see that it might
-represent a spike of requests, rather than the true long-term average.
+concurrencies, which are averages that are generated from reliable numbers, this
+number is an instantaneous sample, and you can see that it might represent a
+spike of requests, rather than the true long-term average.  If this number is
+large, it essentially means that the device is heavily loaded.
 
 =item ios_s
 
-The average throughput of the physical device, in I/O operations per second.
-This column can be used to help you understand how much activity the underlying
-device is actually doing.
+The average throughput of the physical device, in I/O operations per second
+(IOPS).  This column shows the total IOPS the underlying device is handling.  It
+is the sum of rd_io_s and wr_io_s.
 
 =item qtime
 
@@ -3723,9 +3723,9 @@ This column is called busy in pt-diskstats.
 =head1 COLLECTING DATA
 
 It is straightforward to gather a sample of data for this tool.  Files should
-have this format:
+have this format, with a timestamp line preceding each sample of statistics:
 
-   TS <timestamp>  <-- must start with a TS line.
+   TS <timestamp>
    <contents of /proc/diskstats>
    TS <timestamp>
    <contents of /proc/diskstats>