diff --git a/docs/README.md b/docs/README.md
index 0c3fc8850b..234007fdaf 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,23 +1,25 @@
-These docs are written in rST, and are included on the zulip.org website
-as well as on each development installation.  Many of these docs
-have been ported from the internal docs of Zulip Inc.,
-and may need to be updated for use in the open source project.
+These docs are written in [Commonmark
+Markdown](http://commonmark.org/) with a small bit of rST.  We've
+chosen Markdown because it is [easy to
+write](http://commonmark.org/help).  The docs are served in production
+at [zulip.readthedocs.io](https://zulip.readthedocs.io/en/latest/).
 
-To generate HTML docs locally from rST:
+If you want to build the documentation locally (e.g. to test your
+changes), the dependencies are automatically installed as part of
+Zulip development environment provisioning, and you can build the
+documentation using:
 
-   * `pip install sphinx`
-   * In this directory, `make html`. Output appears in a `_build/html` subdirectory.
+```
+cd docs/
+make html
+```
 
-To create rST from MediaWiki input:
-
-   * Use `pandoc -r mediawiki -w rst` on MediaWiki source.
-   * Use unescape.py to remove any leftover HTML entities (often inside <pre>
-     tags and the like).
-
-We can use pandoc to translate mediawiki into reStructuredText, but some things need fixing up:
-
-   * Add page titles.
-   * Review pages for formatting (especially inline code chunks) and content.
-   * Fix wiki links?
-   * Add pages to the table of contents (`index.rst`).
+You can also usually test your changes by pushing a branch to GitHub
+and looking at the content on the GitHub web UI, since GitHub renders
+Markdown.
 
+When editing the dependencies for the Zulip documentation, you'll want
+to edit both the root requirements.txt as well as
+`docs/requirements.readthedocs.txt` (which is used by ReadTheDocs to
+build the documentation quickly, without installing all of Zulip's
+dependencies).