From ae8db93dd04bebeaa3b33538740dc1c19d9f3645 Mon Sep 17 00:00:00 2001
From: Varun Gandhi <varun_gandhi@apple.com>
Date: Sat, 5 Sep 2020 17:30:57 -0700
Subject: [PATCH] [docs] Revise documentation building instructions and move to
 FAQ.md.

---
 README.md               | 21 ---------------------
 docs/HowToGuides/FAQ.md | 30 ++++++++++++++++++++++++++++++
 2 files changed, 30 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index 14cc61b4d0a..6f11e2bd49a 100644
--- a/README.md
+++ b/README.md
@@ -159,24 +159,3 @@ view of the available documentation. In particular, the documents titled
 [Debugging the Swift Compiler](docs/DebuggingTheCompiler.md) and
 [Continuous Integration for Swift](docs/ContinuousIntegration.md) are very
 helpful to understand before submitting your first PR.
-
-### Building Documentation
-
-To read the compiler documentation, start by installing the
-[Sphinx](http://sphinx-doc.org) documentation generator tool by running the
-command:
-
-    easy_install -U "Sphinx < 2.0"
-
-Once complete, you can build the Swift documentation by changing directory into
-[docs](https://github.com/apple/swift/tree/master/docs) and typing `make`. This
-compiles the `.rst` files in the [docs](https://github.com/apple/swift/tree/master/docs)
-directory into HTML in the `docs/_build/html` directory.
-
-Many of the docs are out of date, but you can see some historical design
-documents in the `docs` directory.
-
-Another source of documentation is the standard library itself, located in
-`stdlib`. Much of the language is actually implemented in the library
-(including `Int`), and the standard library gives some examples of what can be
-expressed today.
diff --git a/docs/HowToGuides/FAQ.md b/docs/HowToGuides/FAQ.md
index f4c5002cb01..51cd6d0596a 100644
--- a/docs/HowToGuides/FAQ.md
+++ b/docs/HowToGuides/FAQ.md
@@ -68,6 +68,36 @@ This very depends on what X is, but some broad guidelines are:
    - Use `grep -i -r "mypattern" .`.
 2. Go through the [Documentation Index](/docs/README.md).
 
+### How do I build the documentation as HTML?
+
+You can build the ReST formatted documentation as HTML using Sphinx. Follow
+[Sphinx's installation instructions][] and check that `sphinx-build` is
+available on your `PATH`:
+
+[Sphinx's installation instructions]: https://www.sphinx-doc.org/en/master/usage/installation.html
+
+```sh
+sphinx-build --version
+```
+
+If that succeeds, you can build the documentation using `make`
+
+```sh
+make -C docs
+```
+
+(Tested with `sphinx-build` version 3.2.1.)
+
+This compiles the `.rst` files in the `docs` directory into HTML in the
+`docs/_build/html` directory.
+
+For the Markdown documentation, you can view the rendered HTML directly on
+GitHub. For example, this file is rendered on GitHub at
+https://github.com/apple/swift/tree/master/docs/HowToGuides/FAQ.md .
+
+HTML documentation for the standard library on Darwin platforms is hosted on the
+[Apple Developer website](https://developer.apple.com/documentation/swift/swift_standard_library).
+
 ## Pull Request Workflow
 
 ### How do I format my changes?