Updated README to be more contributor friendly

- Remove doc about deploying and running Cloud Builds since that is
  mostly handled by CI.
- Re-organize to have info on contributing first.

2 files changed, 40 insertions, 56 deletions

diff --git a/Makefile b/Makefile
index 1490120b8..f7f8b72e9 100644
--- a/Makefile
+++ b/Makefile
@@ -21,8 +21,6 @@ public:
 public/app.yaml: public
 	cp -vr cmd/gvisor-website/app.yaml public/
 
-
-
 # Load repositories.
 upstream:
 	mkdir -p upstream
@@ -44,29 +42,38 @@ content/docs/community/sigs: upstream/community $(wildcard upstream/community/si
 $(GO_TARGET): public $(GO_SOURCE)
 	cd cmd/gvisor-website && find . -name "*.go" -exec cp --parents \{\} ../../public \;
 
-deploy: public/app.yaml
-	cd public && $(GCLOUD) app deploy
-.PHONY: deploy
-
 public/static: node_modules config.toml $(shell find archetypes assets content themes -type f | sed 's/ /\\ /g')
 	$(HUGO)
 
-server: all-upstream
-	$(HUGO) server -FD --port 8080
-
 node_modules: package.json package-lock.json
 	# Use npm ci because npm install will update the package-lock.json.
 	# See: https://github.com/npm/npm/issues/18286
 	$(NPM) ci
 
+# Run a local content development server. Redirects will not be supported.
+server: all-upstream
+	$(HUGO) server -FD --port 8080
+.PHONY: server
+
+# Deploy the website to App Engine.
+deploy: public/app.yaml
+	cd public && $(GCLOUD) app deploy
+.PHONY: deploy
+
+# CI related Commmands
+##############################################################################
+
+# Submit a build to Cloud Build manually. Used to test cloudbuild.yaml changes.
 cloud-build:
 	gcloud builds submit --config cloudbuild/cloudbuild.yaml .
 
+# Build and push the hugo Docker image used by Cloud Build.
 hugo-docker-image:
 	docker build --build-arg HUGO_VERSION=$(HUGO_VERSION) -t gcr.io/gvisor-website/hugo:$(HUGO_VERSION) cloudbuild/hugo/
 	docker push gcr.io/gvisor-website/hugo:$(HUGO_VERSION)
 .PHONY: hugo-docker-image
 
+# Build and push the html-proofer image used by Cloud Build.
 htmlproofer-docker-image:
 	docker build --build-arg HTMLPROOFER_VERSION=$(HTMLPROOFER_VERSION) -t gcr.io/gvisor-website/html-proofer:$(HTMLPROOFER_VERSION) cloudbuild/html-proofer/
 	docker push gcr.io/gvisor-website/html-proofer:$(HTMLPROOFER_VERSION)
diff --git a/README.md b/README.md
index fdbbfaa81..29ab01dec 100644
--- a/README.md
+++ b/README.md
@@ -13,18 +13,24 @@ generate CSS files. Please install them before building.
 - Node.js >= 10.15.0 LTS
 - hugo extended >= v0.53
 
-## Building
+## Contributing to Documentation
 
-Build the website using `make`:
+### Using Github
 
-```
-make
-```
+You can use the "Edit this page" link on any documentation page to edit the
+page content directly via GitHub and submit a pull request. This should
+generally be done for relatively small changes.
 
-This will output the App Engine application code, configuration, and html and
-CSS into the `public/` directory.
+### Using Git
 
-## Testing
+You can submit pull requests by making changes in a Git branch. See more
+information on GitHub pull requests
+[here](https://help.github.com/en/articles/about-pull-requests).
+
+Documentation is located in the [content/docs/](content/docs/) directory.
+Documentation is written in markdown with hugo extensions. Please read more
+about [content management](https://gohugo.io/categories/content-management) in
+the hugo documentation.
 
 You can use the hugo web server for testing. This will start a webserver that
 will rebuild the site when you make content changes:
@@ -35,53 +41,24 @@ make server
 
 Access the site at http://localhost:8080
 
-## Deploy
-
-Deploying the website to App Engine requires gcloud. First create a configuration:
-
-```
-{
-  gcloud config configurations create gvisor-website
-  gcloud config set project gvisor-website
-}
-```
+## Building
 
-Deploy the application:
+If you are making changes to App Engine config or application code, you can
+build the website using `make`. This will output the App Engine application
+code, configuration, and html and CSS into the `public/` directory.
 
 ```
-make deploy
+make
 ```
 
-## Editing documentation
-
-Documentation is located in the [content/docs/](content/docs/) directory.
-Documentation is written in markdown with hugo extensions. Please read more
-about [content management](https://gohugo.io/categories/content-management) in
-the hugo documentation.
-
-## Submit a Build
-
-Normally a build is triggered when you push to the gvisor-website repository.
-However, you can submit a build to Cloud Build manually.
-
-As one-time setup, enable the App Engine Admin API, and set IAM roles for the [Cloud Build service
-account](https://cloud.google.com/cloud-build/docs/securing-builds/set-service-account-permissions).
+If you have Go installed you can run a local version of the website via the
+`public/` directory.
 
 ```
 {
-  PROJECT_NUMBER=$(gcloud projects list --filter=projectId:gvisor-website --format="value(projectNumber)")
-  gcloud services enable appengine.googleapis.com
-  gcloud projects add-iam-policy-binding gvisor-website \
-    --member=serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com \
-    --role='roles/appengine.deployer'
-  gcloud projects add-iam-policy-binding gvisor-website \
-    --member=serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com \
-    --role='roles/appengine.serviceAdmin'
+  cd public/
+  go run main.go
 }
 ```
 
-Submit the build.
-
-```
-make cloud-build
-```
+Access the site at http://localhost:8080