From c7913cb1d1f0c6ad1aca7f09e24b07186251856a Mon Sep 17 00:00:00 2001
From: Oliver Gorwits <oliver@cpan.org>
Date: Thu, 12 Sep 2019 21:29:48 +0100
Subject: [PATCH] add first run doc note as suggested by Stuart Kendrick

---
 lib/App/Netdisco.pm | 30 ++++++++++++++++++++++--------
 1 file changed, 22 insertions(+), 8 deletions(-)

diff --git a/lib/App/Netdisco.pm b/lib/App/Netdisco.pm
index 2e7f9db4..c7334212 100644
--- a/lib/App/Netdisco.pm
+++ b/lib/App/Netdisco.pm
@@ -215,16 +215,21 @@ port control, etc):
 
  ~/bin/netdisco-backend start
 
-I<note:> Whenever you upgrade your operating system, you should delete the
-C<~/perl5> directory and re-run the C<curl> command above, to update
-Netdisco's C library bindings.
+=head1 First Run
 
-I<also note:> You should take care not to run C<< netdisco-backend >> and the
-Netdisco 1.x daemon at the same time. Similarly, if you use the device
-discovery with Netdisco 2, disable your system's cron jobs for the Netdisco
-1.x poller.
+After installing Netdisco for the first time, you must manually discover at
+least one device on your network.  Choose a device which speaks CDP, FDP, or
+LLDP and thus knows about its neighbors; Netdisco will then start following
+this chain of neighbors to discover the rest of your network.
 
-We have several other pages with tips for
+To do this, either go to the web interface and enter an IP or fully qualified
+domain name, or perform the following step at the command line:
+
+ ~/bin/netdisco-do discover {name or IP address of a switch or router}
+
+=head1 Further Reading
+
+We have several pages with tips for
 L<alternate deployment scenarios|https://github.com/netdisco/netdisco/wiki/Install-Tips>,
 L<understanding and troubleshooting Netdisco|https://github.com/netdisco/netdisco/wiki/Troubleshooting>,
 L<tips and tricks for specific platforms|https://github.com/netdisco/netdisco/wiki/Vendor-Tips>,
@@ -237,6 +242,15 @@ L<Release Notes|https://github.com/netdisco/netdisco/wiki/Release-Notes>.
 
 =head1 Upgrading from 2.x
 
+I<note:> Whenever you upgrade your operating system, you should delete the
+C<~/perl5> directory and re-run the C<curl> command above, to update
+Netdisco's C library bindings.
+
+I<also note:> You should take care not to run C<< netdisco-backend >> and the
+Netdisco 1.x daemon at the same time. Similarly, if you use the device
+discovery with Netdisco 2, disable your system's cron jobs for the Netdisco
+1.x poller.
+
 If you're running a version of Netdisco prior to 2.x then you should follow
 the full installation instructions, above. This process is for upgrading
 version 2.x only.