Update notes about reading/writing docs

docs/README.txt

@@ -1,7 +1,34 @@
+If you are reading Tahoe-LAFS documentation
+-------------------------------------------
 
-Note: http://tahoe-lafs.readthedocs.io/en/latest/ is the preferred place to
+If you are reading Tahoe-LAFS documentation at a code hosting site or
-read this documentation (GitHub doesn't render cross-document links or
+from a checked-out source tree, the preferred place to view the docs
-images). If you're reading this on https://github.com/tahoe-lafs/tahoe-lafs ,
+is http://tahoe-lafs.readthedocs.io/en/latest/.  Code-hosting sites do
-or from a checked-out source tree, then either run `tox -e docs` and open
+not render cross-document links or images correctly.
-_build/html/index.html in your browser, or view the pre-rendered trunk copy
+
-at http://tahoe-lafs.readthedocs.io/en/latest/
+
+If you are writing Tahoe-LAFS documentation
+-------------------------------------------
+
+To edit Tahoe-LAFS docs, you will need a checked-out source tree.  You
+can edit the `.rst` files in this directory using a text editor, and
+then generate HTML output using Sphinx, a program that can produce its
+output in HTML and other formats.
+
+The files with `.rst` extension use reStructuredText markup format,
+which is the format Sphinx natively handles.  To learn more about
+Sphinx, and for a friendly primer on reStructuredText, please see
+Sphinx project's documentation, available at:
+
+https://www.sphinx-doc.org/
+
+If you have tox installed, you can run `tox -e docs` and then open the
+resulting docs/_build/html/index.html in your web browser.
+
+If you have Sphinx and Make installed, you can also run `make html`
+within docs directory.  You may also need to install some additional
+Python packages, such as setuptools and recommonmark.
+
+Note that Sphinx can also process comments in Python source code to
+generate API documentation.  Tahoe-LAFS currently does not use Sphinx
+for this purpose.