Clarify recommended install steps (#68)

Signed-off-by: Andy Fingerhut <andy_fingerhut@alum.wustl.edu>

README.md

@@ -49,45 +49,42 @@ Some things not included, that one must get from Intel:
 
 # Setup
 
+The installation scripts for these programs attempt to enable installing
+multiple versions of it, in different directories, on the same system.
+That said, if you have unusual problems installing it, consider attempting
+to follow the install steps on a freshly installed and supported version of
+Linux, to see if that helps.
+
 ```bash
 git clone https://github.com/p4lang/open-p4studio.git
 cd open-p4studio
 ```
 
+Proceed by choosing one of the following options:
+
++ a "batch build", with a default choice of packages selected
+  for you.  See instructions in the next section.  This option
+  is recommended if you are trying out this software for the first
+  time.
++ Or, if you wish to customize the set of packages to be installed,
+  skip down to the section "Installation with customization of options"
+
+
 # Batch build and install Intel® P4 Studio Software Development Environment (SDE)
 
 This script checks that you have the right processor type, and
 sufficient RAM and free disk space, and then installs the SDE using a
-default choice for options.  See later below for instructions that let
-you customize the installation choices.
+default choice for options.
 
 ```bash
 # If you have not already done so, update submodules
 git submodule update --init --recursive
 ./p4studio/p4studio profile apply ./p4studio/profiles/testing.yaml
-./create-setup-script.sh > ~/setup-open-p4studio.bash
 ```
 
-# Run instructions
-
-Do this command in each terminal where you wish to use the SDE:
-
-```bash
-source $HOME/setup-open-p4studio.bash
-```
-
-You may wish to add that line to your `$HOME/.bashrc` file to automate
-this.
-
-This command creates many virtual Ethernet interfaces that are used
-when running tests involving the Tofino model, so it can send and
-receive packets on those interfaces.  It only needs to be done once on
-a system after it has been rebooted, before running tests that require
-these interfaces:
+When that script completes, proceed by following the steps in section
+"Finishing the installation" below.
 
-```bash
-sudo ${SDE_INSTALL}/bin/veth_setup.sh 128
-```
 
 # Installation with customization of options
 
@@ -149,9 +146,70 @@ sudo ${SDE_INSTALL}/bin/veth_setup.sh 128
     h)	Select **Yes** to configure advanced options. Advanced options include p4rt, TDI, and SAI configurations.
 
     i)	The created profile details are displayed at this stage. Save the profile details in a YAML file for future use. 
-    
+
 3. Script completes the SDE installation process.
 
+When that script completes, proceed by following the steps in section
+"Finishing the installation" below.
+
+
+# Finishing the installation
+
+Run this command from the `open-p4studio` directory where you
+installed the software:
+
+```bash
+./create-setup-script.sh > ~/setup-open-p4studio.bash
+```
+
+If you only install one version of this software on a system,
+you will likely find it very convenient to add a line like
+the following to your `~/.bashrc` file:
+
+```bash
+source ~/setup-open-p4studio.bash
+```
+
+If you do not do this, you will need to do that command once in each
+terminal or shell session where you wish to use this software.
+
+Tip for advanced users: If you install more than one version of this
+software on the same system, and want to switch between them, create
+_different_ `setup-<name>.bash` files, one for each version you want
+to use.
+
+
+## Optional step: Install documentation
+
+You can generate HTML documentation using the following command:
+
+```bash
+cd $SDE/build/pkgsrc/bf-drivers
+make doc-driver install
+```
+
+At least some of this documentation is then browsable via the command:
+
+```bash
+xdg-open $SDE_INSTALL/share/doc/bf-drivers/html/index.html
+```
+
+Or you can use any other method appropriate on your system to open a
+browser to that HTML file.
+
+
+# Run instructions
+
+This command creates many virtual Ethernet interfaces that are used
+when running tests involving the Tofino model, so it can send and
+receive packets on those interfaces.  It only needs to be done once on
+a system after it has been rebooted, before running tests that require
+these interfaces:
+
+```bash
+sudo ${SDE_INSTALL}/bin/veth_setup.sh 128
+```
+
 
 # Run the Tofino Model