Updates to source and doc build pages (#11464)

* Updates to source and doc build pages.

Clarifies a few points for newbies.

* Fixed spelling error

And added spellcheck info to website README file.

README.md

@@ -42,7 +42,7 @@
 
 Druid is a high performance real-time analytics database. Druid's main value add is to reduce time to insight and action.
 
-Druid is designed for workflows where fast queries and ingest really matter. Druid excels at powering UIs, running operational (ad-hoc) queries, or handling high concurrency. Consider Druid as an open source alternative to data warehouses for a variety of use cases.
+Druid is designed for workflows where fast queries and ingest really matter. Druid excels at powering UIs, running operational (ad-hoc) queries, or handling high concurrency. Consider Druid as an open source alternative to data warehouses for a variety of use cases. The [design documentation](https://druid.apache.org/docs/latest/design/architecture.html) explains the key concepts.
 
 ### Getting started
 

docs/development/build.md

@@ -23,30 +23,32 @@ title: "Build from source"
   -->
 
 
-You can build Apache Druid directly from source. Please note that these instructions are for building the latest stable version of Druid.
+You can build Apache Druid directly from source. Use the version of this page
-For building the latest code in master, follow the instructions [here](https://github.com/apache/druid/blob/master/docs/development/build.md).
+that matches the version you want to build.
-
+For building the latest code in master, follow the latest version of this page
+[here](https://github.com/apache/druid/blob/master/docs/development/build.md):
+make sure it has `/master/` in the URL.
 
 #### Prerequisites
 
-##### Installing Java and Maven:
+##### Installing Java and Maven
+
 - JDK 8, 8u92+. We recommend using an OpenJDK distribution that provides long-term support and open-source licensing,
   like [Amazon Corretto](https://aws.amazon.com/corretto/) or [Azul Zulu](https://www.azul.com/downloads/zulu/).
 - [Maven version 3.x](http://maven.apache.org/download.cgi)
 
-##### Other Dependencies
+##### Other dependencies
-- for distribution build, Python and yaml module are required
 
+- Distribution builds require Python 3.x and the `pyyaml` module
 
-##### Downloading the source:
+##### Downloading the source
 
 ```bash
 git clone git@github.com:apache/druid.git
 cd druid
 ```
 
-
+#### Building from source
-#### Building the source
 
 The basic command to build Druid from source is:
 
@@ -71,13 +73,21 @@ mvn clean install -Papache-release,dist,rat -DskipTests
 ```
 #### Potential issues
 
-##### Issue
+##### Missing `pyyaml`
+
 You are building Druid from source following the instructions on this page but you get
 ```
 [ERROR] Failed to execute goal org.codehaus.mojo:exec-maven-plugin:1.6.0:exec (generate-binary-license) on project distribution: Command execution failed.: Process exited with an error: 1 (Exit value: 1) -> [Help 1]
 ```
 
 Resolution: Make sure you have Python installed as well as the `yaml` module:
-```
+
+```bash
 pip install pyyaml
-```
+```
+
+On some systems, ensure you use the Python 3.x version of `pip`:
+
+```bash
+pip3 install pyyaml
+```

website/README.md

@@ -21,10 +21,52 @@
 
 This website was created with [Docusaurus](https://docusaurus.io/).
 
-To edit this documentation run:
+To view documentation run:
 
 `npm install`
 
-Then run
+Then run:
 
 `npm start`
+
+The current version of the web site appears in your browser. Edit pages with
+your favorite editor. Refresh the web page after each edit to review your changes.
+
+## Dependencies
+
+* [NodeJS](https://nodejs.org/en/download/). Use the version Docusaurus specifies, not a
+newer one. (For example, if 12.x is requested, don't install 16.x.)
+Docusaurus may require a version
+newer than that available in your Linux package repository, but older than the
+latest version. See
+[this page](https://github.com/nodesource/distributions/blob/master/README.md) to
+find the version required by Docusaurus.
+* The [Yarn](https://classic.yarnpkg.com/en/) dependency from Docusaurus is optional.
+(This Yarn is not the Hadoop resource manager, it is a package manager for Node.js).
+* [Docusaurus](https://docusaurus.io/docs/installation). Installed automatically
+as part of the the above `npm` commands.
+
+## Variables
+
+Documentation pages can refer to a number of special variables using the
+`{{var}}` syntax:
+
+* `DRUIDVERSION` - the version of Druid in which the page appears. Allows
+creating links to files of the same version on GitHub.
+
+The variables are not replaced when running the web site locally using the
+`start` command above.
+
+## Spellcheck
+
+Please run a spellcheck before issuing a pull request to avoid a build failure
+due to spelling issues. Run:
+
+```bash
+npm run link-lint
+npm run spellcheck
+```
+
+If you introduce new (correctly spelled) project names or technical terms, add
+them to the dictionary in the `.spelling` file in this directory. Also, terms
+enclosed in backticks are not spell checked. Example: \``symbolName`\`