plugin/autopath: slightly tweaks the docs (#4188)

* plugin/autopath: slightly tweaks the docs

Make the first sentence of the intro slightly easier to read. Refer to a
bugs section, just like other plugins do.

Signed-off-by: Miek Gieben <miek@miek.nl>

* Update plugin/autopath/README.md

Co-authored-by: Chris O'Haver <cohaver@infoblox.com>

Co-authored-by: Chris O'Haver <cohaver@infoblox.com>

1 files changed, 15 insertions, 14 deletions

diff --git a/plugin/autopath/README.md b/plugin/autopath/README.md
index b1b4b165c..eedbf5ee7 100644
--- a/plugin/autopath/README.md
+++ b/plugin/autopath/README.md
@@ -6,13 +6,13 @@
 
 ## Description
 
-If it sees a query that matches the first element of the configured search path, *autopath* will
+If the *autopath* plugin sees a query that matches the first element of the configured search path, it will
 follow the chain of search path elements and return the first reply that is not NXDOMAIN. On any
 failures, the original reply is returned. Because *autopath* returns a reply for a name that wasn't
-the original question it will add a CNAME that points from the original name (with the search path
+the original question, it will add a CNAME that points from the original name (with the search path
 element in it) to the name of this answer.
 
-**Note**: There are several known issues.  See section below.
+**Note**: There are several known issues, see the "Bugs" section below.
 
 ## Syntax
 
@@ -25,7 +25,7 @@ autopath [ZONE...] RESOLV-CONF
   plugin. For instance `@kubernetes`, will call out to the kubernetes plugin (for each
   query) to retrieve the search list it should use.
 
-If a plugin implements the `AutoPather` interface then it can be used.
+If a plugin implements the `AutoPather` interface then it can be used by *autopath*.
 
 ## Metrics
 
@@ -50,18 +50,19 @@ autopath @kubernetes
 
 Use the search path dynamically retrieved from the *kubernetes* plugin.
 
-## Known Issues
+## Bugs
 
-In Kubernetes, *autopath* can derive the wrong namespace of a client Pod (and therefore wrong search path)
-in the following case.  To properly build the search path of a client *autopath* needs to
-know the namespace of the a Pod making a DNS request. To do this, it relies on the
-*kubernetes* plugin's Pod cache to resolve the client's IP address to a Pod.  The Pod cache is maintained by
-an API watch on Pods.  When Pod IP assignments change, the Kubernetes API notifies CoreDNS via the API watch.
+In Kubernetes, *autopath* can derive the wrong namespace of a client Pod (and therefore wrong search
+path) in the following case. To properly build the search path of a client *autopath* needs to know
+the namespace of the a Pod making a DNS request. To do this, it relies on the *kubernetes* plugin's
+Pod cache to resolve the client's IP address to a Pod. The Pod cache is maintained by an API watch
+on Pods. When Pod IP assignments change, the Kubernetes API notifies CoreDNS via the API watch.
 However, that notification is not instantaneous. In the case that a Pod is deleted, and it's IP is
-immediately provisioned to a Pod in another namespace, and that new Pod make a DNS lookup *before* the API watch
-can notify CoreDNS of the change, *autopath* will resolve the IP to the previous Pod's namespace.
+immediately provisioned to a Pod in another namespace, and that new Pod make a DNS lookup *before*
+the API watch can notify CoreDNS of the change, *autopath* will resolve the IP to the previous Pod's
+namespace.
 
 In Kubernetes, *autopath* is not compatible with Pods running from Windows nodes.
 
-If the server side search ultimately results in a negative answer (e.g. `NXDOMAIN`), then the client will
-fruitlessly search all paths manually, thus negating the *autopath* optimization.
+If the server side search ultimately results in a negative answer (e.g. `NXDOMAIN`), then the client
+will fruitlessly search all paths manually, thus negating the *autopath* optimization.