From c90e4b1bc5c843878ed4048f37249fe78a841c46 Mon Sep 17 00:00:00 2001 From: Fred Lifton Date: Wed, 29 Oct 2014 16:43:18 -0700 Subject: [PATCH] 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 (github: fredlf) Conflicts: docs/README.md Revisions to style guide based on review. Docker-DCO-1.1-Signed-off-by: Fred Lifton (github: fredlf) More Style Guide revisions based on review. Docker-DCO-1.1-Signed-off-by: Fred Lifton (github: fredlf) A few more style guide copy edits Docker-DCO-1.1-Signed-off-by: Fred Lifton (github: fredlf) --- docs/README.md | 44 +++++++++++++++----------------------------- 1 file changed, 15 insertions(+), 29 deletions(-) diff --git a/docs/README.md b/docs/README.md index 27ed7eef11..f5ccb753da 100755 --- a/docs/README.md +++ b/docs/README.md @@ -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