Add a mention of 80 column lines and reflow the document to hide the

evidence.

Docker-DCO-1.1-Signed-off-by: SvenDowideit <SvenDowideit@home.org.au> (github: SvenDowideit)

docs/README.md

@@ -1,37 +1,35 @@
 # Docker Documentation
 
-The source for Docker documentation is here under `sources/` and uses
+The source for Docker documentation is here under `sources/` and uses extended
-extended Markdown, as implemented by [mkdocs](http://mkdocs.org).
+Markdown, as implemented by [mkdocs](http://mkdocs.org).
 
-The HTML files are built and hosted on `https://docs.docker.io`, and
+The HTML files are built and hosted on `https://docs.docker.io`, and update
-update automatically after each change to the master or release branch
+automatically after each change to the master or release branch of [Docker on
-of [Docker on GitHub](https://github.com/dotcloud/docker)
+GitHub](https://github.com/dotcloud/docker) thanks to post-commit hooks. The
-thanks to post-commit hooks. The "docs" branch maps to the "latest"
+"docs" branch maps to the "latest" documentation and the "master" (unreleased
-documentation and the "master" (unreleased development) branch maps to
+development) branch maps to the "master" documentation.
-the "master" documentation.
 
 ## Branches
 
-**There are two branches related to editing docs**: `master` and a
+**There are two branches related to editing docs**: `master` and a `docs`
-`docs` branch. You should always edit documentation on a local branch
+branch. You should always edit documentation on a local branch of the `master`
-of the `master` branch, and send a PR against `master`.
+branch, and send a PR against `master`.
 
-That way your fixes will automatically get included in later releases,
+That way your fixes will automatically get included in later releases, and docs
-and docs maintainers can easily cherry-pick your changes into the
+maintainers can easily cherry-pick your changes into the `docs` release branch.
-`docs` release branch. In the rare case where your change is not
+In the rare case where your change is not forward-compatible, you may need to
-forward-compatible, you may need to base your changes on the `docs`
+base your changes on the `docs` branch.
-branch.
 
 Also, now that we have a `docs` branch, we can keep the
-[http://docs.docker.io](http://docs.docker.io) docs up to date with any
+[http://docs.docker.io](http://docs.docker.io) docs up to date with any bugs
-bugs found between `docker` code releases.
+found between `docker` code releases.
 
 **Warning**: When *reading* the docs, the
-[http://beta-docs.docker.io](http://beta-docs.docker.io) documentation
+[http://beta-docs.docker.io](http://beta-docs.docker.io) documentation may
-may include features not yet part of any official docker release. The
+include features not yet part of any official docker release. The `beta-docs`
-`beta-docs` site should be used only for understanding bleeding-edge
+site should be used only for understanding bleeding-edge development and
-development and `docs.docker.io` (which points to the `docs`
+`docs.docker.io` (which points to the `docs` branch`) should be used for the
-branch`) should be used for the latest official release.
+latest official release.
 
 ## Contributing
 
@@ -41,59 +39,61 @@ branch`) should be used for the latest official release.
 
 ## Getting Started
 
-Docker documentation builds are done in a Docker container, which
+Docker documentation builds are done in a Docker container, which installs all
-installs all the required tools, adds the local `docs/` directory and
+the required tools, adds the local `docs/` directory and builds the HTML docs.
-builds the HTML docs. It then starts a HTTP server on port 8000 so that
+It then starts a HTTP server on port 8000 so that you can connect and see your
-you can connect and see your changes.
+changes.
 
 In the root of the `docker` source directory:
 
     make docs
 
-If you have any issues you need to debug, you can use `make docs-shell` and
+If you have any issues you need to debug, you can use `make docs-shell` and then
-then run `mkdocs serve`
+run `mkdocs serve`
+
+## Style guide
+
+The documentation is written with paragraphs wrapped at 80 colum lines to make
+it easier for terminal use.
 
 ### Examples
 
-When writing examples give the user hints by making them resemble what
+When writing examples give the user hints by making them resemble what they see
-they see in their shell:
+in their shell:
 
 - Indent shell examples by 4 spaces so they get rendered as code.
 - Start typed commands with `$ ` (dollar space), so that they are easily
-differentiated from program output.
+  differentiated from program output.
 - Program output has no prefix.
 - Comments begin with `# ` (hash space).
 - In-container shell commands begin with `$$ ` (dollar dollar space).
 
 ### Images
 
-When you need to add images, try to make them as small as possible
+When you need to add images, try to make them as small as possible (e.g. as
-(e.g. as gifs). Usually images should go in the same directory as the
+gifs). Usually images should go in the same directory as the `.md` file which
-`.md` file which references them, or in a subdirectory if one already
+references them, or in a subdirectory if one already exists.
-exists.
 
 ## Working using GitHub's file editor
 
-Alternatively, for small changes and typos you might want to use
+Alternatively, for small changes and typos you might want to use GitHub's built
-GitHub's built in file editor. It allows you to preview your changes
+in file editor. It allows you to preview your changes right on-line (though
-right on-line (though there can be some differences between GitHub
+there can be some differences between GitHub Markdown and [MkDocs
-Markdown and [MkDocs Markdown](http://www.mkdocs.org/user-guide/writing-your-docs/)).
+Markdown](http://www.mkdocs.org/user-guide/writing-your-docs/)).  Just be
-Just be careful not to create many commits. And you must still
+careful not to create many commits. And you must still [sign your
-[sign your work!](../CONTRIBUTING.md#sign-your-work)
+work!](../CONTRIBUTING.md#sign-your-work)
 
 ## Publishing Documentation
 
-To publish a copy of the documentation you need a `docs/awsconfig`
+To publish a copy of the documentation you need a `docs/awsconfig` To make life
-file containing AWS settings to deploy to. The release script will
+easier for file containing AWS settings to deploy to. The release script will
 create an s3 if needed, and will then push the files to it.
 
-    [profile dowideit-docs]
+    [profile dowideit-docs] aws_access_key_id = IHOIUAHSIDH234rwf....
-    aws_access_key_id = IHOIUAHSIDH234rwf....
+    aws_secret_access_key = OIUYSADJHLKUHQWIUHE......  region = ap-southeast-2
-    aws_secret_access_key = OIUYSADJHLKUHQWIUHE......
-    region = ap-southeast-2
 
-The `profile` name must be the same as the name of the bucket you are
+The `profile` name must be the same as the name of the bucket you are deploying
-deploying to - which you call from the `docker` directory:
+to - which you call from the `docker` directory:
 
     make AWS_S3_BUCKET=dowideit-docs docs-release