diff --git a/plugins/inputs/EXAMPLE_README.md b/plugins/inputs/EXAMPLE_README.md
index 4ebedda87..b60d48c91 100644
--- a/plugins/inputs/EXAMPLE_README.md
+++ b/plugins/inputs/EXAMPLE_README.md
@@ -4,18 +4,22 @@ The example plugin gathers metrics about example things.  This description
 explains at a high level what the plugin does and provides links to where
 additional information can be found.
 
-### Configuration:
+### Configuration
 
 This section contains the default TOML to configure the plugin.  You can
 generate it using `telegraf --usage <plugin-name>`.
 
 ```toml
-# Description
 [[inputs.example]]
   example_option = "example_value"
 ```
 
-### Metrics:
+#### example_option
+
+A more in depth description of an option can be provided here, but only do so
+if the option cannot be fully described in the sample config.
+
+### Metrics
 
 Here you should add an optional description and links to where the user can
 get more information about the measurements.
@@ -38,10 +42,10 @@ mapped to the output.
   - fields:
     - field3 (integer, bytes)
 
-### Sample Queries:
+### Sample Queries
 
-This section should contain some useful InfluxDB queries that can be used to
-get started with the plugin or to generate dashboards.  For each query listed,
+This section can contain some useful InfluxDB queries that can be used to get
+started with the plugin or to generate dashboards.  For each query listed,
 describe at a high level what data is returned.
 
 Get the max, mean, and min for the measurement in the last hour:
@@ -49,7 +53,12 @@ Get the max, mean, and min for the measurement in the last hour:
 SELECT max(field1), mean(field1), min(field1) FROM measurement1 WHERE tag1=bar AND time > now() - 1h GROUP BY tag
 ```
 
-### Example Output:
+### Troubleshooting
+
+This optional section can provide basic troubleshooting steps that a user can
+perform.
+
+### Example Output
 
 This section shows example output in Line Protocol format.  You can often use
 `telegraf --input-filter <plugin-name> --test` or use the `file` output to get
diff --git a/plugins/inputs/disk/README.md b/plugins/inputs/disk/README.md
index fa84264be..5359cca62 100644
--- a/plugins/inputs/disk/README.md
+++ b/plugins/inputs/disk/README.md
@@ -9,7 +9,6 @@ https://en.wikipedia.org/wiki/Df_(Unix) for more details.
 ### Configuration:
 
 ```toml
-# Read metrics about disk usage by mount point
 [[inputs.disk]]
   ## By default stats will be gathered for all mount points.
   ## Set mount_points will restrict the stats to only the specified mount points.
@@ -49,6 +48,17 @@ docker run -v /:/hostfs:ro -e HOST_MOUNT_PREFIX=/hostfs -e HOST_PROC=/hostfs/pro
     - inodes_total (integer, files)
     - inodes_used (integer, files)
 
+### Troubleshooting
+
+On Linux, the list of disks is taken from the `/proc/self/mounts` file and a
+[statfs] call is made on the second column.  If any expected filesystems are
+missing ensure that the `telegraf` user can read these files:
+```
+$ sudo -u telegraf cat /proc/self/mounts | grep sda2
+/dev/sda2 /home ext4 rw,relatime,data=ordered 0 0
+$ sudo -u telegraf stat /home
+```
+
 ### Example Output:
 
 ```
@@ -58,4 +68,4 @@ disk,fstype=autofs,mode=rw,path=/net free=0i,inodes_free=0i,inodes_total=0i,inod
 disk,fstype=autofs,mode=rw,path=/home free=0i,inodes_free=0i,inodes_total=0i,inodes_used=0i,total=0i,used=0i,used_percent=0 1453832006274169688
 ```
 
-
+[statfs]: http://man7.org/linux/man-pages/man2/statfs.2.html