Adds new Docs Style Guide.

Includes changes to mkdocs yml and removes style info from docs Read Me, adding a link instead.

Docker-DCO-1.1-Signed-off-by: Fred Lifton <fred.lifton@docker.com> (github: fredlf)

Conflicts:
	docs/README.md

Revisions to style guide based on review.

Docker-DCO-1.1-Signed-off-by: Fred Lifton <fred.lifton@docker.com> (github: fredlf)

More Style Guide revisions based on review.

Docker-DCO-1.1-Signed-off-by: Fred Lifton <fred.lifton@docker.com> (github: fredlf)

A few more style guide copy edits

Docker-DCO-1.1-Signed-off-by: Fred Lifton <fred.lifton@docker.com> (github: fredlf)
This commit is contained in:
Fred Lifton 2014-10-29 16:43:18 -07:00 committed by Tibor Vass
parent d83b068933
commit c90e4b1bc5
1 changed files with 15 additions and 29 deletions

View File

@ -11,9 +11,8 @@ development) branch maps to the "master" documentation.
## Contributing
- Follow the contribution guidelines ([see
`../CONTRIBUTING.md`](../CONTRIBUTING.md)).
- [Remember to sign your work!](../CONTRIBUTING.md#sign-your-work)
Be sure to follow the [contribution guidelines](../CONTRIBUTING.md)).
In particular, [remember to sign your work!](../CONTRIBUTING.md#sign-your-work)
## Getting Started
@ -41,26 +40,10 @@ to the menu definition in the `docs/mkdocs.yml` file.
## Style guide
The documentation is written with paragraphs wrapped at 80 column lines to make
it easier for terminal use.
### Examples
When writing examples, give the user hints by making them resemble what they see
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.
- 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 (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.
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.
## Working using GitHub's file editor
@ -73,11 +56,11 @@ work!](../CONTRIBUTING.md#sign-your-work)
## Branches
**There are two branches related to editing docs**: `master` and a `docs`
branch. You should always edit the documentation on a local branch of the `master`
**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 edits will automatically get included in later releases, and docs
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.
@ -95,8 +78,10 @@ found between Docker code releases.
## Publishing Documentation
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 AWS settings to deploy to.
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 release script will create an s3 if needed, and will then push the files to it.
[profile dowideit-docs] aws_access_key_id = IHOIUAHSIDH234rwf....
@ -115,7 +100,8 @@ also update the root docs pages by running
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,
> **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 `$(boot2docker shellinit)` to see the correct variable to set. The command