Add more documentation for script/build.go

.github/CONTRIBUTING.md

@@ -26,11 +26,15 @@ Prerequisites:
 - Go 1.13+ for building the binary
 - Go 1.15+ for running the test suite
 
-Build with: `make` or `go build -o bin/gh ./cmd/gh`
+Build with:
+* Unix-like systems: `make`
+* Windows: `go run script/build.go`
 
-Run the new binary as: `./bin/gh`
+Run the new binary as:
+* Unix-like systems: `bin/gh`
+* Windows: `bin\gh`
 
-Run tests with: `make test` or `go test ./...`
+Run tests with: `go test ./...`
 
 ## Submitting a pull request
 

Makefile

@@ -5,6 +5,8 @@ export CGO_CFLAGS
 CGO_LDFLAGS ?= $(filter -g -L% -l% -O%,${LDFLAGS})
 export CGO_LDFLAGS
 
+## The following tasks delegate to `script/build.go` so they can be run cross-platform.
+
 .PHONY: bin/gh
 bin/gh: script/build
 	@script/build bin/gh
@@ -20,10 +22,13 @@ clean: script/build
 manpages: script/build
 	@script/build manpages
 
+# just a convenience task around `go test`
 .PHONY: test
 test:
 	go test ./...
 
+## Site-related tasks are exclusively intended for use by the GitHub CLI team and for our release automation.
+
 site:
 	git clone https://github.com/github/cli.github.com.git "$@"
 
@@ -45,6 +50,8 @@ endif
 	rm -f site/index.html.bak
 	git -C site commit -m '$(GITHUB_REF:refs/tags/v%=%)' index.html
 
+## Install/uninstall tasks are here for use on *nix platform. On Windows, there is no equivalent.
+
 DESTDIR :=
 prefix  := /usr/local
 bindir  := ${prefix}/bin