Rearrange the existing info a little, and add example style guide
Docker-DCO-1.1-Signed-off-by: Sven Dowideit (github: SvenDowideit)
-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
