Update install docs, part of advanced docs, and share feature docs

8 files changed, 19 insertions, 13 deletions

diff --git a/docs/source/_static/screenshots/private-key.png b/docs/source/_static/screenshots/private-key.png
new file mode 100644
index 00000000..13d1a9d4
--- /dev/null
+++ b/docs/source/_static/screenshots/private-key.png
diff --git a/docs/source/_static/screenshots/share-files.png b/docs/source/_static/screenshots/share-files.png
index f7d39726..b5f0223f 100644
--- a/docs/source/_static/screenshots/share-files.png
+++ b/docs/source/_static/screenshots/share-files.png
diff --git a/docs/source/_static/screenshots/share-sharing.png b/docs/source/_static/screenshots/share-sharing.png
index 756277d0..47f00975 100644
--- a/docs/source/_static/screenshots/share-sharing.png
+++ b/docs/source/_static/screenshots/share-sharing.png
diff --git a/docs/source/_static/screenshots/share-torbrowser.png b/docs/source/_static/screenshots/share-torbrowser.png
index 8d628640..4eeabf0e 100644
--- a/docs/source/_static/screenshots/share-torbrowser.png
+++ b/docs/source/_static/screenshots/share-torbrowser.png
diff --git a/docs/source/_static/screenshots/share.png b/docs/source/_static/screenshots/share.png
index 18797581..91e42dd1 100644
--- a/docs/source/_static/screenshots/share.png
+++ b/docs/source/_static/screenshots/share.png
diff --git a/docs/source/advanced.rst b/docs/source/advanced.rst
index 96f7141b..76fb59fa 100644
--- a/docs/source/advanced.rst
+++ b/docs/source/advanced.rst
@@ -61,6 +61,8 @@ If nothing happens to you, you can cancel the service before it's scheduled to s
 
 .. image:: _static/screenshots/advanced-schedule-stop-timer.png
 
+.. _cli:
+
 Command-line Interface
 ----------------------
 
@@ -76,6 +78,8 @@ Then run it like this::
 
     onionshare-cli --help
 
+For more information, see the `CLI readme file <https://github.com/onionshare/onionshare/blob/develop/cli/README.md>`_ in the git repository.
+
 If you installed OnionShare using the Linux Snapcraft package, you can also just run ``onionshare.cli`` to access the command-line interface version.
 
 Usage
diff --git a/docs/source/features.rst b/docs/source/features.rst
index 0c72809b..d2dcb4ca 100644
--- a/docs/source/features.rst
+++ b/docs/source/features.rst
@@ -5,19 +5,21 @@ How OnionShare Works
 
 Web servers are started locally on your computer and made accessible to other people as `Tor <https://www.torproject.org/>`_ `onion services <https://community.torproject.org/onion-services/>`_.
 
-By default, OnionShare web addresses are protected with a private key (Client Authentication). A typical OnionShare address might look something like this::
+By default, OnionShare web addresses are protected with a private key.
 
-    http://by4im3ir5nsvygprmjq74xwplrkdgt44qmeapxawwikxacmr3dqzyjad.onion
+OnionShare addresses look something like this::
 
-And the Private key might look something like this::
+    http://oy5oaslxxzwib7fsjaiz5mjeyg3ziwdmiyeotpjw6etxi722pn7pqsyd.onion
 
-    EM6UK3LFM7PFLX63DVZIUQQPW5JV5KO6PB3TP3YNA4OLB3OH7AQA
+And private keys might look something like this::
 
-You're responsible for securely sharing that URL, and the private key, using a communication channel of your choice like in an encrypted chat message, or using something less secure like unencrypted e-mail, depending on your `threat model <https://ssd.eff.org/module/your-security-plan>`_.
+    K3N3N3U3BURJW46HZEZV2LZHBPKEFAGVN6DPC7TY6FHWXT7RLRAQ
 
-The people you send the URL to then copy and paste it into their `Tor Browser <https://www.torproject.org/>`_ to access the OnionShare service.
+You're responsible for securely sharing that URL and private key using a communication channel of your choice like in an encrypted chat message, or using something less secure like unencrypted e-mail, depending on your `threat model <https://ssd.eff.org/module/your-security-plan>`_.
 
-Tor Browser will then prompt for the private key in an authentication dialog, which the person can also then copy and paste in.
+The people you send the URL to then copy and paste it into their `Tor Browser <https://www.torproject.org/>`_ to access the OnionShare service. Tor Browser will then prompt for the private key, which the people can also then copy and paste in.
+
+.. image:: _static/screenshots/private-key.png
 
 If you run OnionShare on your laptop to send someone files, and then suspend it before the files are sent, the service will not be available until your laptop is unsuspended and on the Internet again. OnionShare works best when working with people in real-time.
 
@@ -43,7 +45,7 @@ When you're ready to share, click the "Start sharing" button. You can always cli
 
 .. image:: _static/screenshots/share-sharing.png
 
-Now that you have a OnionShare, copy the address and send it to the person you want to receive the files. If the files need to stay secure, or the person is otherwise exposed to danger, use an encrypted messaging app.
+Now that you have a OnionShare, copy the address and the private key and send it to the person you want to receive the files. If the files need to stay secure, or the person is otherwise exposed to danger, use an encrypted messaging app.
 
 That person then must load the address in Tor Browser. After logging in with the private key, the files can be downloaded directly from your computer by clicking the "Download Files" link in the corner.
 
diff --git a/docs/source/install.rst b/docs/source/install.rst
index e542048b..c5dd8197 100644
--- a/docs/source/install.rst
+++ b/docs/source/install.rst
@@ -9,7 +9,7 @@ You can download OnionShare for Windows and macOS from the `OnionShare website <
 .. _linux:
 
 Linux
-----------------
+-----
 
 There are various ways to install OnionShare for Linux, but the recommended way is to use either the `Flatpak <https://flatpak.org/>`_ or the `Snap <https://snapcraft.io/>`_ package.
 Flatpak and Snap ensure that you'll always use the newest version and run OnionShare inside of a sandbox.
@@ -24,10 +24,10 @@ You can also download and install PGP-signed ``.flatpak`` or ``.snap`` packages
 
 .. _pip:
 
-Any OS with pip
----------------
+Command-line only
+-----------------
 
-If you want to install OnionShare just for the command line (onionshare-cli), please see the `README <https://github.com/onionshare/onionshare/blob/develop/cli/README.md>`_ in the Git repository for installation instructions with python package manager pip.
+You can install just the command line version of OnionShare on any operating system using the Python package manager ``pip``. See :ref:`cli` for more information.
 
 .. _verifying_sigs:
 
@@ -73,6 +73,6 @@ The expected output looks like this::
     gpg:          There is no indication that the signature belongs to the owner.
     Primary key fingerprint: 927F 419D 7EC8 2C2F 149C  1BD1 403C 2657 CD99 4F73
 
-If you don't see 'Good signature from', there might be a problem with the integrity of the file (malicious or otherwise), and you should not install the package. (The "WARNING:" shown above, is not a problem with the package, it only means you haven't already defined any level of 'trust' of Micah's PGP key.)
+If you don't see ``Good signature from``, there might be a problem with the integrity of the file (malicious or otherwise), and you should not install the package. (The ``WARNING:`` shown above, is not a problem with the package, it only means you haven't defined a level of "trust" of Micah's PGP key.)
 
 If you want to learn more about verifying PGP signatures, the guides for `Qubes OS <https://www.qubes-os.org/security/verifying-signatures/>`_ and the `Tor Project <https://support.torproject.org/tbb/how-to-verify-signature/>`_ may be useful.