Update readme for github-repo files

README.md

@@ -12,16 +12,23 @@ All Markdown files here are run through [tianon's fork of `markdownfmt`](https:/
 -	create a `README-short.txt` (required, 100 char max)
 -	create a `content.md` (required)
 -	create a `license.md` (required)
+-	create a `github-repo` (required)
 -	add a `logo.png` (recommended)
--	edit `update.sh` as needed (see below)
--	run `./markdownfmt.sh -l myimage` to verify that the format of your markdown files is compliant with `tianon/markdownfmt`. In case you see any file names, markdownfmt detected some issues, which might result in a failed build during continuous integration.
--	optionally run `./update.sh myimage` to generate `myimage/README.md` for review. **Note:** do not actually commit the `README.md` file; it is automatically generated/committed before being uploaded to DockerHub.
+
+Optionally:
+
+-	run `./update.sh myimage` to generate `myimage/README.md` for your review. **Note:** do not actually commit the `README.md` file; it is automatically generated/committed before being uploaded to Docker Hub.
+-	run `./markdownfmt.sh -l myimage` to verify whether format of your markdown files is compliant to `tianon/markdownfmt`. In case you see any file names, markdownfmt detected some issues, which might result in a failed build during continuous integration. run `./markdownfmt.sh -d myimage` to see a diff of changes required to pass.
+
+# How do I update an image's docs
+
+To update `README.md` for a specific image do not edit `README.md` directly. Please edit `content.md` or another appropriate file within the folder. To see the changes, run `./update.sh myimage` from the repo root, but do not add the `README.md` changes to your pull request. See also `markdownfmt.sh` point [above](#how-do-i-add-a-new-images-docs).
 
 # What are all these files?
 
 ## `update.sh`
 
-This is the main script used to generate the `README.md` files for each image. When a new image is added that is not under the `docker-library` namespace on GitHub, a new entry must be added to the `otherRepos` array in this script. Accepted arguments are which image(s) you want to update and no arguments to update all of them.
+This is the main script used to generate the `README.md` files for each image. The generated file is committed along with the files used to generate it (see below on what customizations are available). Accepted arguments are which image(s) you want to update or no arguments to update all of them.
 
 ## `generate-repo-stub-readme.sh`
 
@@ -82,6 +89,14 @@ This file should contain a link to the license for the main software in the imag
 View [license information](http://golang.org/LICENSE) for the software contained in this image.
 ```
 
+## `<image name>/github-repo`
+
+This file should contain the URL to the GitHub repository for the Dockerfiles that become the images. The file should be in a single line ending in a newline with no extraneous whitespace. Only one GitHub repo per image repository is supported. It is used in generating links. Here is an example for `golang`:
+
+```text
+https://github.com/docker-library/golang
+```
+
 ## `<image name>/user-feedback.md`
 
 This file is an optional override of the default `user-feedback.md` for those repositories with different issue and contributing policies.