Merge pull request #5587 from SvenDowideit/docs-examples-style-guide

Rearrange the existing info a little, and add example style guide

docs/README.md

@@ -1,8 +1,4 @@
-Docker Documentation
-====================
-
-Overview
---------
+# Docker Documentation
 
 The source for Docker documentation is here under `sources/` and uses
 extended Markdown, as implemented by [mkdocs](http://mkdocs.org).
@@ -37,8 +33,13 @@ may include features not yet part of any official docker release. The
 development and `docs.docker.io` (which points to the `docs`
 branch`) should be used for the latest official release.
 
-Getting Started
----------------
+## Contributing
+
+- Follow the contribution guidelines ([see
+  `../CONTRIBUTING.md`](../CONTRIBUTING.md)).
+- [Remember to sign your work!](../CONTRIBUTING.md#sign-your-work)
+
+## Getting Started
 
 Docker documentation builds are done in a Docker container, which
 installs all the required tools, adds the local `docs/` directory and
@@ -47,40 +48,40 @@ you can connect and see your changes.
 
 In the root of the `docker` source directory:
 
-    cd docker
-
-Run:
-
     make docs
 
 If you have any issues you need to debug, you can use `make docs-shell` and
 then run `mkdocs serve`
 
-# Contributing
-
-* Follow the contribution guidelines ([see
-  `../CONTRIBUTING.md`](../CONTRIBUTING.md)).
-* [Remember to sign your work!](../CONTRIBUTING.md#sign-your-work)
+### Examples
 
-Working using GitHub's file editor
-----------------------------------
+When writing examples give the user hints by making them resemble what
+they see in their shell:
 
-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). Just be careful not to create many commits.
-And you must still [sign your work!](../CONTRIBUTING.md#sign-your-work)
+- 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.
+- Program output has no prefix.
+- Comments begin with `# ` (hash space).
+- In-container shell commands begin with `$$ ` (dollar dollar space).
 
-Images
-------
+### Images
 
 When you need to add images, try to make them as small as possible
 (e.g. as gifs). Usually images should go in the same directory as the
 `.md` file which references them, or in a subdirectory if one already
 exists.
 
-Publishing Documentation
-------------------------
+## 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
 
 To publish a copy of the documentation you need a `docs/awsconfig`
 file containing AWS settings to deploy to. The release script will