Merge pull request #11222 from moxiegirl/update-howto-docs

Updating in light of new contributors guide. Got verbal ok from Jess to pull janky is acting janky.

docs/README.md

@@ -1,156 +1,255 @@
 # Docker Documentation
 
-The source for Docker documentation is here under `sources/` and uses extended
-Markdown, as implemented by [MkDocs](http://mkdocs.org).
+The source for Docker documentation is in this directory under `sources/`. Our
+documentation uses extended Markdown, as implemented by
+[MkDocs](http://mkdocs.org).  The current release of the Docker documentation
+resides on [http://docs.docker.com](http://docs.docker.com).
 
-The HTML files are built and hosted on
-[http://docs.docker.com](http://docs.docker.com), and update automatically
-after each change to the `docs` branch of [Docker on
-GitHub](https://github.com/docker/docker) thanks to post-commit hooks.
+## Understanding the documentation branches and processes
 
-## Contributing
+Docker has two primary branches for documentation:
 
-Be sure to follow the [contribution guidelines](../CONTRIBUTING.md).
-In particular, [remember to sign your work!](../CONTRIBUTING.md#sign-your-work)
+| Branch   | Description                    | URL (published via commit-hook)                                              |
+|----------|--------------------------------|------------------------------------------------------------------------------|
+| `docs`   | Official release documentation | [http://docs.docker.com](http://docs.docker.com)                             |
+| `master` | Merged but unreleased development work    | [http://docs.master.dockerproject.com](http://docs.master.dockerproject.com) |
 
-## Getting Started
+Additions and updates to upcoming releases are made in a feature branch off of
+the `master` branch. The Docker maintainers also support a `docs` branch that
+contains the last release of documentation.
 
-Docker documentation builds are done in a Docker container, which installs all
-the required tools, adds the local `docs/` directory and builds the HTML docs.
-It then starts a HTTP server on port 8000 so that you can connect and see your
-changes.
+After a release, documentation updates are continually merged into `master` as
+they occur. This work includes new documentation for forthcoming features, bug
+fixes, and other updates. Docker's CI system automatically builds and updates
+the `master` documentation after each merge and posts it to
+[http://docs.master.dockerproject.com](http://docs.master.dockerproject.com). 
 
-In the root of the `docker` source directory:
+Periodically, the Docker maintainers update `docs.docker.com` between official
+releases of Docker. They do this by cherry-picking commits from `master`,
+merging them into `docs`,  and then publishing the result.
 
-    $ make docs
-    .... (lots of output) ....
-    docker run --rm -it  -e AWS_S3_BUCKET -p 8000:8000 "docker-docs:master" mkdocs serve
-    Running at: http://0.0.0.0:8000/
-    Live reload enabled.
-    Hold ctrl+c to quit.
+In the rare case where a change is not forward-compatible, changes may be made
+on other branches by special arrangement with the Docker maintainers.
 
-If you have any issues you need to debug, you can use `make docs-shell` and then
-run `mkdocs serve`
+### Quickstart for documentation contributors
+
+If you are a new or beginner contributor, we encourage you to read through the
+[our detailed contributors
+guide](https://docs.docker.com/project/who-written-for/). The guide explains in
+detail, with examples, how to contribute. If you are an experienced contributor
+this quickstart should be enough to get you started.
+
+The following is the essential workflow for contributing to the documentation:
+
+1. Fork the `docker/docker` repository.
+
+2. Clone the repository to your local machine.
+
+3. Select an issue from `docker/docker` to work on or submit a proposal of your
+own.
+
+4. Create a feature branch from `master` in which to work.
+
+	By basing from `master` your work is automatically included in the next
+	release. It also allows docs maintainers to easily cherry-pick your changes
+	into the `docs` release branch. 
+
+4. Modify existing or add new `.md` files to the `docs/sources` directory.
 
-## Testing the links
+	If you add a new document (`.md`) file, you must also add it to the
+	appropriate section of the `docs/mkdocs.yml` file in this repository.
 
-You can use `make docs-test` to generate a report of missing links that are referenced in
-the documentation - there should be none.
 
-## Adding a new document
+5.  As you work, build the documentation site locally to see your changes.
 
-New document (`.md`) files are added to the documentation builds by adding them
-to the menu definition in the `docs/mkdocs.yml` file.
+	The `docker/docker` repository contains a `Dockerfile` and a `Makefile`.
+	Together, these create a development environment in which you can build and
+	run a container running the Docker documentation website. To build the
+	documentation site, enter `make docs` at the root of your `docker/docker`
+	fork:
+	
+		$ make docs
+		.... (lots of output) ....
+		docker run --rm -it  -e AWS_S3_BUCKET -p 8000:8000 "docker-docs:master" mkdocs serve
+		Running at: http://0.0.0.0:8000/
+		Live reload enabled.
+		Hold ctrl+c to quit.
+	
+	
+	The build creates an image containing all the required tools, adds the local
+	`docs/` directory and generates the HTML files. Then, it runs a Docker
+	container with this image.
+
+	The container exposes port 8000 on the localhost so that you can connect and
+	see your changes. If you are running Boot2Docker, use the `boot2docker ip`
+	to get the address of your server.
+
+6.  Check your writing for style and mechanical errors.
+
+	Use our [documentation style
+	guide](https://docs.docker.com/project/doc-style/) to check style. There are
+	several [good grammar and spelling online
+	checkers](http://www.hemingwayapp.com/) that can check your writing
+	mechanics.
+
+7.  Squash your commits on your branch.
+
+8.  Make a pull request from your fork back to Docker's `master` branch.
+
+9.  Work with the reviewers until your change is approved and merged.
+
+### Debugging and testing
+
+If you have any issues you need to debug, you can use `make docs-shell` and then
+run `mkdocs serve`. You can use `make docs-test` to generate a report of missing
+links that are referenced in the documentation—there should be none.
 
 ## Style guide
 
-If you have questions about how to write for Docker's documentation (e.g.,
-questions about grammar, syntax, formatting, styling, language, or tone) please
-see the [style guide](sources/contributing/docs_style-guide.md). If something
-isn't clear in the guide, please submit a PR to help us improve it.
+If you have questions about how to write for Docker's documentation, please see
+the [style guide](sources/project/doc-style.md). The style guide provides
+guidance about grammar, syntax, formatting, styling, language, or tone. If
+something isn't clear in the guide, please submit an issue to let us know or
+submit a pull request to help us improve it.
 
-## Working using GitHub's file editor
 
-Alternatively, for small changes and typos you might want to use GitHub's built-
-in file editor. It allows you to preview your changes right on-line (though
-there can be some differences between GitHub Markdown and [MkDocs
-Markdown](http://www.mkdocs.org/user-guide/writing-your-docs/)).  Just be
-careful not to create many commits. And you must still [sign your
-work!](../CONTRIBUTING.md#sign-your-work)
+## Publishing documentation (for Docker maintainers)
 
-## Branches
+To publish Docker's documentation you need to have Docker up and running on your
+machine. You'll also need a `docs/awsconfig` file containing the settings you
+need to access the AWS bucket you'll be deploying to.
 
-| Branch   | Description                    | URL (published via commit-hook)                                              |
-|----------|--------------------------------|------------------------------------------------------------------------------|
-| `docs`   | Official release documentation | [http://docs.docker.com](http://docs.docker.com)                             |
-| `master` | Unreleased development work    | [http://docs.master.dockerproject.com](http://docs.master.dockerproject.com) |
+The process for publishing is to build first to an AWS bucket, verify the build,
+and then publish the final release.
 
-**There are two branches related to editing docs**: `master` and `docs`. You
-should always edit the documentation on a local branch of the `master` branch,
-and send a PR against `master`.  That way your fixes will automatically get
-included in later releases, and docs maintainers can easily cherry-pick your
-changes into the `docs` release branch.  In the rare case where your change is
-not forward-compatible, you may need to base your changes on the `docs` branch.
+1. Have Docker installed and running on your machine.
 
-Also, since there is a separate `docs` branch, we can keep
-[http://docs.docker.com](http://docs.docker.com) up to date with any bugs found
-between Docker code releases.
+2. Ask the core maintainers for the `awsconfig` file.
 
-## Publishing Documentation
+3. Copy the `awsconfig` file to the `docs/` directory.
 
-To publish a copy of the documentation you need to have Docker up and running on
-your machine. You'll also need a `docs/awsconfig` file containing the settings
-you need to access the AWS bucket you'll be deploying to.
+	The `awsconfig` file contains the profiles of the S3 buckets for our
+	documentation sites. (If needed, the release script creates an S3 bucket and
+	pushes the files to it.)  Each profile has this format:
 
-The release script will create an s3 if needed, and will then push the files to it.
+		[profile dowideit-docs]
+		aws_access_key_id = IHOIUAHSIDH234rwf....
+		aws_secret_access_key = OIUYSADJHLKUHQWIUHE......
+		region = ap-southeast-2
 
-    [profile dowideit-docs]
-    aws_access_key_id = IHOIUAHSIDH234rwf....
-    aws_secret_access_key = OIUYSADJHLKUHQWIUHE......
-    region = ap-southeast-2
+	The `profile` name must be the same as the name of the bucket you are
+	deploying to.
 
-The `profile` name must be the same as the name of the bucket you are deploying
-to - which you call from the `docker` directory:
+4. Call the `make` from the `docker` directory.
 
-    make AWS_S3_BUCKET=dowideit-docs docs-release
+    	$ make AWS_S3_BUCKET=dowideit-docs docs-release
 
-This will publish _only_ to the `http://bucket-url/v1.2/` version of the
-documentation.
+	This publishes _only_ to the `http://bucket-url/v1.2/` version of the
+	documentation.
 
-If you're publishing the current release's documentation, you need to
-also update the root docs pages by running
+5.  If you're publishing the current release's documentation, you need to also
+update the root docs pages by running
 
-    make AWS_S3_BUCKET=dowideit-docs BUILD_ROOT=yes docs-release
+     	$ make AWS_S3_BUCKET=dowideit-docs BUILD_ROOT=yes docs-release
 
-> **Note:**
-> if you are using Boot2Docker on OSX and the above command returns an error,
-> `Post http:///var/run/docker.sock/build?rm=1&t=docker-docs%3Apost-1.2.0-docs_update-2:
-> dial unix /var/run/docker.sock: no such file or directory', you need to set the Docker
-> host. Run `eval "$(boot2docker shellinit)"` to see the correct variable to set. The command
-> will return the full `export` command, so you can just cut and paste.
+### Errors publishing using Boot2Docker
+
+Sometimes, in a Boot2Docker environment, the publishing procedure returns this
+error:
+
+	Post http:///var/run/docker.sock/build?rm=1&t=docker-docs%3Apost-1.2.0-docs_update-2:
+	dial unix /var/run/docker.sock: no such file or directory.
+
+If this happens, set the Docker host. Run the following command to set the
+variables in your shell:
+
+		$ eval "$(boot2docker shellinit)"
 
 ## Cherry-picking documentation changes to update an existing release.
 
-Whenever the core team makes a release, they publish the documentation based
-on the `release` branch (which is copied into the `docs` branch). The
-documentation team can make updates in the meantime, by cherry-picking changes
-from `master` into any of the docs branches.
+Whenever the core team makes a release, they publish the documentation based on
+the `release` branch. At that time, the  `release` branch is copied into the
+`docs` branch. The documentation team makes updates between Docker releases by
+cherry-picking changes from `master` into any of the documentation branches.
+Typically, we cherry-pick into the `docs` branch.
+
+For example, to update the current release's docs, do the following:
+
+1. Go to your `docker/docker` fork and get the latest from master.
+
+    	$ git fetch upstream
+        
+2. Checkout a new branch based on `upstream/docs`.
+
+	You should give your new branch a descriptive name.
+
+		$ git checkout -b post-1.2.0-docs-update-1 upstream/docs
+	
+3. In a browser window, open [https://github.com/docker/docker/commits/master].
+
+4. Locate the merges you want to publish.
+
+	You should only cherry-pick individual commits; do not cherry-pick merge
+	commits. To minimize merge conflicts, start with the oldest commit and work
+	your way forward in time.
+
+5. Copy the commit SHA from GitHub.
 
-For example, to update the current release's docs:
+6. Cherry-pick the commit.
+	
+	 	$ git cherry-pick -x fe845c4
+	
+7. Repeat until you have cherry-picked everything you want to merge.
 
-    git fetch upstream
-    git checkout -b post-1.2.0-docs-update-1 upstream/docs
-    # Then go through the Merge commit linked to PR's (making sure they apply
-    to that release)
-    # see https://github.com/docker/docker/commits/master
-    git cherry-pick -x fe845c4
-    # Repeat until you have cherry picked everything you will propose to be merged
-    git push upstream post-1.2.0-docs-update-1
+8. Push your changes to your fork.
 
-Then make a pull request to merge into the `docs` branch, __NOT__ into master.
+    	$ git push origin post-1.2.0-docs-update-1
 
-Once the PR has the needed `LGTM`s, merge it, then publish to our beta server
-to test:
+9. Make a pull request to merge into the `docs` branch.
 
-    git fetch upstream
-    git checkout docs
-    git reset --hard upstream/docs
-    make AWS_S3_BUCKET=beta-docs.docker.io BUILD_ROOT=yes docs-release
+	Do __NOT__ merge into `master`.
 
-Then go to http://beta-docs.docker.io.s3-website-us-west-2.amazonaws.com/
-to view your results and make sure what you published is what you wanted.
+10. Have maintainers review your pull request.
 
-When you're happy with it, publish the docs to our live site:
+11. Once the PR has the needed "LGTMs", merge it on GitHub.
 
-    make AWS_S3_BUCKET=docs.docker.com BUILD_ROOT=yes DISTRIBUTION_ID=C2K6......FL2F docs-release
+12. Return to your local fork and make sure you are still on the `docs` branch.
 
-Test the uncached version of the live docs at http://docs.docker.com.s3-website-us-east-1.amazonaws.com/
+		$ git checkout docs
+
+13. Fetch your merged pull request from `docs`.
+
+		$ git fetch upstream/docs
+	
+14. Ensure your branch is clean and set to the latest.
+
+   	 	$ git reset --hard upstream/docs
     
-Note that the new docs will not appear live on the site until the cache (a complex,
-distributed CDN system) is flushed. The `make docs-release` command will do this
-_if_ the `DISTRIBUTION_ID` is set to the Cloudfront distribution ID (ask the meta
-team) - this will take at least 15 minutes to run and you can check its progress
-with the CDN Cloudfront Chrome addin.
+15. Copy the `awsconfig` file into the `docs` directory.
+    
+16. Make the beta documentation
+
+    	$ make AWS_S3_BUCKET=beta-docs.docker.io BUILD_ROOT=yes docs-release
+
+17. Open [the beta
+website](http://beta-docs.docker.io.s3-website-us-west-2.amazonaws.com/) site
+and make sure what you published is correct.
+
+19. When you're happy with your content, publish the docs to our live site:
+
+   		$ make AWS_S3_BUCKET=docs.docker.com BUILD_ROOT=yes
+DISTRIBUTION_ID=C2K6......FL2F docs-release
+
+20. Test the uncached version of the live docs at [http://docs.docker.com.s3-website-us-east-1.amazonaws.com/]
+
+
+### Caching and the docs
+
+New docs do not appear live on the site until the cache (a complex, distributed
+CDN system) is flushed. The `make docs-release` command flushes the cache _if_
+the `DISTRIBUTION_ID` is set to the Cloudfront distribution ID. The cache flush
+can take at least 15 minutes to run and you can check its progress with the CDN
+Cloudfront Purge Tool Chrome app.
 
 ## Removing files from the docs.docker.com site