ARROW-4332: [Website] Improve documentation for publishing site
Author: Andy Grove <andygrove73@gmail.com>
Author: Wes McKinney <wesm+git@apache.org>
Author: Krisztián Szűcs <szucs.krisztian@gmail.com>
Closes #3498 from andygrove/ARROW-4332 and squashes the following commits:
350fabdf <Wes McKinney> md formatting
07250eb6 <Andy Grove> remove duplicate instruction
54403799 <Andy Grove> Improve documentation for publishing the site
39929d7a <Andy Grove> Merge remote-tracking branch 'upstream/master'
17ee1596 <Andy Grove> Merge remote-tracking branch 'upstream/master'
88267899 <Krisztián Szűcs> ARROW-4273: Fix verification script to use cf201901 conda-forge label
diff --git a/README.md b/README.md
index 412051c..7a287ec 100644
--- a/README.md
+++ b/README.md
@@ -17,32 +17,53 @@
under the License.
-->
-## Apache Arrow Website
+# Apache Arrow Website
-### Development instructions
+## Overview
-If you are planning to publish the website, you must first clone the arrow-site
-git repository:
+Site content is maintained in the main Arrow repository, mostly in markdown
+format. [Jekyll](https://jekyllrb.com/) is used to generate HTML files that can
+then be committed to the [arrow-site](https://github.com/apache/arrow-site)
+repository.
+
+## Prerequisites
+
+With Ruby >= 2.1 installed, run the following commands to install
+[Jekyll](https://jekyllrb.com/).
+
+```shell
+gem install jekyll bundler
+bundle install
+```
+
+If you are planning to publish the website, you must clone the arrow-site git
+repository. Run this command from the `site` directory so that `asf-site` is a
+subdirectory of `site`.
```shell
git clone --branch=asf-site https://github.com/apache/arrow-site.git asf-site
```
-Now, with Ruby >= 2.1 installed, run:
+Also, from the `site` directory, run the following command to import the format
+markdown documents so that they will rendered.
-```shell
-gem install jekyll bundler
-bundle install
-
-# This imports the format Markdown documents so they will be rendered
+```
scripts/sync_format_docs.sh
+```
+## Previewing the site
+
+From the `site` directory, run the following to generate HTML files and run the
+web site locally.
+
+```
bundle exec jekyll serve
```
-### Publishing
+## Publishing
-After following the above instructions the base `site/` directory, run:
+After following the above instructions, run the following commands from the
+`site` directory:
```shell
JEKYLL_ENV=production bundle exec jekyll build
