@@ -169,8 +169,28 @@ pages:

 - ['terms/filesystem.md', '**HIDDEN**']

 - ['terms/image.md', '**HIDDEN**']

+<<<<<<< HEAD

+<<<<<<< HEAD

+# Project:

+- ['project/index.md', '**HIDDEN**']

+- ['project/who-written-for.md', 'Project', 'README first']

+=======

 # Contribute:

-- ['contributing/index.md', '**HIDDEN**']

-- ['contributing/contributing.md', 'Contribute', 'Contributing']

-- ['contributing/devenvironment.md', 'Contribute', 'Development environment']

-- ['contributing/docs_style-guide.md', 'Contribute', 'Documentation style guide']

+- ['project/index.md', '**HIDDEN**']

+- ['project/project.md', 'Contribute', 'Contributing']

+# Birthday Tree

+- ['project/who-written-for.md', 'Project', 'README for contributors']

+>>>>>>> a252b2f... Renaming and removing old files

+=======

+# Project:

+- ['project/index.md', '**HIDDEN**']

+- ['project/who-written-for.md', 'Project', 'README first']

+>>>>>>> 6f40419... Tweaking from last run thru

+- ['project/set-up-prereqs.md', 'Project', 'Set up prerequisites'] 

+- ['project/set-up-dev-env.md', 'Project', 'Work with a development container'] 

+- ['project/test-and-docs.md', 'Project', 'Run tests and test documentation']

+- ['project/make-a-contribution.md', 'Project', 'Make a project contribution'] 

+- ['project/advanced-contributing.md', 'Project', 'Advanced contributing']

+- ['project/get-help.md', 'Project', 'Where to get help']

+- ['project/coding-style.md', 'Project', 'Coding style guide']

+- ['project/doc-style.md', 'Project', 'Documentation style guide']

deleted file mode 100644

@@ -1,7 +0,0 @@

-# Contributing

-

-## Contents:

-

- - [Contributing to Docker](contributing/)

- - [Setting Up a Dev Environment](devenvironment/)

-

deleted file mode 100644

@@ -1,24 +0,0 @@

-page_title: Contribution Guidelines

-page_description: Contribution guidelines: create issues, conventions, pull requests

-page_keywords: contributing, docker, documentation, help, guideline

-

-# Contributing to Docker

-

-Want to hack on Docker? Awesome!

-

-The repository includes [all the instructions you need to get started](

-https://github.com/docker/docker/blob/master/CONTRIBUTING.md).

-

-The [developer environment Dockerfile](

-https://github.com/docker/docker/blob/master/Dockerfile)

-specifies the tools and versions used to test and build Docker.

-

-If you're making changes to the documentation, see the [README.md](

-https://github.com/docker/docker/blob/master/docs/README.md).

-

-The [documentation environment Dockerfile](

-https://github.com/docker/docker/blob/master/docs/Dockerfile)

-specifies the tools and versions used to build the Documentation.

-

-Further interesting details can be found in the [Packaging hints](

-https://github.com/docker/docker/blob/master/project/PACKAGERS.md).

deleted file mode 100644

@@ -1,169 +0,0 @@

-page_title: Setting Up a Dev Environment

-page_description: Guides on how to contribute to docker

-page_keywords: Docker, documentation, developers, contributing, dev environment

-

-# Setting Up a Dev Environment

-

-To make it easier to contribute to Docker, we provide a standard

-development environment. It is important that the same environment be

-used for all tests, builds and releases. The standard development

-environment defines all build dependencies: system libraries and

-binaries, go environment, go dependencies, etc.

-

-**Things you need:**

-

- * Docker

- * git

- * make

-

-## Install Docker

-

-Docker's build environment itself is a Docker container, so the first

-step is to install Docker on your system.

-

-You can follow the [install instructions most relevant to your

-system](https://docs.docker.com/installation/). Make sure you

-have a working, up-to-date docker installation, then continue to the

-next step.

-

-## Install tools used for this tutorial

-

-Install `git`; honest, it's very good. You can use

-other ways to get the Docker source, but they're not anywhere near as

-easy.

-

-Install `make`. This tutorial uses our base Makefile

-to kick off the docker containers in a repeatable and consistent way.

-Again, you can do it in other ways but you need to do more work.

-

-## Check out the Source

-

-    $ git clone https://git@github.com/docker/docker

-    $ cd docker

-

-To checkout a different revision just use `git checkout`

-with the name of branch or revision number.

-

-## Build the Environment

-

-This following command builds a development environment using the

-`Dockerfile` in the current directory. Essentially, it installs all

-the build and runtime dependencies necessary to build and test Docker.

-Your first build will take some time to complete. On Linux systems and on Mac

-OS X from within the `boot2docker` shell:

-

-    $ make build

-    

-> **Note**:

-> On Mac OS X, the Docker make targets such as `build`, `binary`, and `test`

-> should **not** be built by the 'root' user. Therefore, you shouldn't use `sudo` when 

-> running these commands on OS X.

-> On Linux, we suggest you add your current user to the `docker` group via

-> [these

-> instructions](http://docs.docker.com/installation/ubuntulinux/#giving-non-root-access).

-

-If the build is successful, congratulations! You have produced a clean

-build of docker, neatly encapsulated in a standard build environment.

-

-

-## Build the Docker Binary

-

-To create the Docker binary, run this command:

-

-    $ make binary

-

-This will create the Docker binary in `./bundles/<version>-dev/binary/`. If you

-do not see files in the `./bundles` directory in your host, your `BIND_DIR`

-setting is not set quite right. You want to run the following command:

-

-    $ make BIND_DIR=. binary

-

-If you are on a non-Linux platform, e.g., OSX, you'll want to run `make cross`

-or `make BIND_DIR=. cross`.

-

-### Using your built Docker binary

-

-The binary is available outside the container in the directory

-`./bundles/<version>-dev/binary/`. You can swap your

-host docker executable with this binary for live testing - for example,

-on ubuntu:

-

-    $ sudo service docker stop ; sudo cp $(which docker) $(which docker)_ ; sudo cp ./bundles/<version>-dev/binary/docker-<version>-dev $(which docker);sudo service docker start

-

-> **Note**: 

-> Its safer to run the tests below before swapping your hosts docker binary.

-

-## Run the Tests

-

-To execute the test cases, run this command:

-

-    $ make test

-

-If the test are successful then the tail of the output should look

-something like this

-

-    --- PASS: TestWriteBroadcaster (0.00 seconds)

-    === RUN TestRaceWriteBroadcaster

-    --- PASS: TestRaceWriteBroadcaster (0.00 seconds)

-    === RUN TestTruncIndex

-    --- PASS: TestTruncIndex (0.00 seconds)

-    === RUN TestCompareKernelVersion

-    --- PASS: TestCompareKernelVersion (0.00 seconds)

-    === RUN TestHumanSize

-    --- PASS: TestHumanSize (0.00 seconds)

-    === RUN TestParseHost

-    --- PASS: TestParseHost (0.00 seconds)

-    === RUN TestParseRepositoryTag

-    --- PASS: TestParseRepositoryTag (0.00 seconds)

-    === RUN TestGetResolvConf

-    --- PASS: TestGetResolvConf (0.00 seconds)

-    === RUN TestParseRelease

-    --- PASS: TestParseRelease (0.00 seconds)

-    === RUN TestDependencyGraphCircular

-    --- PASS: TestDependencyGraphCircular (0.00 seconds)

-    === RUN TestDependencyGraph

-    --- PASS: TestDependencyGraph (0.00 seconds)

-    PASS

-    ok      github.com/docker/docker/utils        0.017s

-

-If `$TESTFLAGS` is set in the environment, it will pass extra arguments

-to `go test`. You can use this to select certain tests to run, e.g.,

-

-    $ TESTFLAGS='-test.run \^TestBuild\$' make test

-

-Only those test cases matching the regular expression inside quotation marks will be tested.

-

-If the output indicates "FAIL" and you see errors like this:

-

-    server.go:1302 Error: Insertion failed because database is full: database or disk is full

-

-    utils_test.go:179: Error copy: exit status 1 (cp: writing '/tmp/docker-testd5c9-[...]': No space left on device

-

-Then you likely don't have enough memory available the test suite. 2GB

-is recommended.

-

-## Use Docker

-

-You can run an interactive session in the newly built container:

-

-    $ make shell

-

-    # type 'exit' or Ctrl-D to exit

-

-## Build And View The Documentation

-

-If you want to read the documentation from a local website, or are

-making changes to it, you can build the documentation and then serve it

-by:

-

-    $ make docs

-    

-    # when its done, you can point your browser to http://yourdockerhost:8000

-    # type Ctrl-C to exit

-

-**Need More Help?**

-

-If you need more help then hop on to the [#docker-dev IRC

-channel](irc://chat.freenode.net#docker-dev) or post a message on the

-[Docker developer mailing

-list](https://groups.google.com/d/forum/docker-dev).

deleted file mode 100644

@@ -1,276 +0,0 @@

-page_title: Style Guide for Docker Documentation

-page_description: Style guide for Docker documentation describing standards and conventions for contributors

-page_keywords: style, guide, docker, documentation

-

-# Docker documentation: style & grammar conventions

-

-## Style standards

-

-Over time, different publishing communities have written standards for the style

-and grammar they prefer in their publications. These standards are called

-[style guides](http://en.wikipedia.org/wiki/Style_guide). Generally, Docker’s

-documentation uses the standards described in the

-[Associated Press's (AP) style guide](http://en.wikipedia.org/wiki/AP_Stylebook). 

-If a question about syntactical, grammatical, or lexical practice comes up,

-refer to the AP guide first. If you don’t have a copy of (or online subscription

-to) the AP guide, you can almost always find an answer to a specific question by

-searching the web. If you can’t find an answer, please ask a

-[maintainer](https://github.com/docker/docker/blob/master/docs/MAINTAINERS) and

-we will find the answer.

-

-That said, please don't get too hung up on using correct style. We'd rather have

-you submit good information that doesn't conform to the guide than no

-information at all. Docker's tech writers are always happy to help you with the

-prose, and we promise not to judge or use a red pen!

-

-> **Note:**

-> The documentation is written with paragraphs wrapped at 80 column lines to

-> make it easier for terminal use. You can probably set up your favorite text

-> editor to do this automatically for you.

-

-### Prose style

-

-In general, try to write simple, declarative prose. We prefer short,

-single-clause sentences and brief three-to-five sentence paragraphs. Try to

-choose vocabulary that is straightforward and precise. Avoid creating new terms,

-using obscure terms or, in particular, using a lot of jargon. For example, use

-"use" instead of leveraging "leverage".

-

-That said, don’t feel like you have to write for localization or for

-English-as-a-second-language (ESL) speakers specifically. Assume you are writing

-for an ordinary speaker of English with a basic university education. If your

-prose is simple, clear, and straightforward it will translate readily.

-

-One way to think about this is to assume Docker’s users are generally university

-educated and read at at least a "16th" grade level (meaning they have a

-university degree). You can use a [readability

-tester](https://readability-score.com/) to help guide your judgement. For

-example, the readability score for the phrase "Containers should be ephemeral"

-is around the 13th grade level (first year at university), and so is acceptable.

-

-In all cases, we prefer clear, concise communication over stilted, formal

-language. Don't feel like you have to write documentation that "sounds like

-technical writing."

-

-### Metaphor and figurative language

-

-One exception to the "don’t write directly for ESL" rule is to avoid the use of

-metaphor or other

-[figurative language](http://en.wikipedia.org/wiki/Literal_and_figurative_language) to

-describe things. There are too many cultural and social issues that can prevent

-a reader from correctly interpreting a metaphor.

-

-## Specific conventions

-

-Below are some specific recommendations (and a few deviations) from AP style

-that we use in our docs.

-

-### Contractions

-

-As long as your prose does not become too slangy or informal, it's perfectly

-acceptable to use contractions in our documentation. Make sure to use

-apostrophes correctly.

-

-### Use of dashes in a sentence.

-

-Dashes refers to the en dash (–) and the em dash (—). Dashes can be used to

-separate parenthetical material.

-

-Usage Example: This is an example of a Docker client – which uses the Big Widget

-to run – and does x, y, and z.

-

-Use dashes cautiously and consider whether commas or parentheses would work just

-as well. We always emphasize short, succinct sentences.

-

-More info from the always handy [Grammar Girl site](http://www.quickanddirtytips.com/education/grammar/dashes-parentheses-and-commas).

-

-### Pronouns

-

-It's okay to use first and second person pronouns. Specifically, use "we" to

-refer to Docker and "you" to refer to the user. For example, "We built the

-`exec` command so you can resize a TTY session."

-

-As much as possible, avoid using gendered pronouns ("he" and "she", etc.).

-Either recast the sentence so the pronoun is not needed or, less preferably,

-use "they" instead. If you absolutely can't get around using a gendered pronoun,

-pick one and stick to it. Which one you choose is up to you. One common

-convention is to use the pronoun of the author's gender, but if you prefer to

-default to "he" or "she", that's fine too.

-

-### Capitalization 

-

-#### In general

-

-Only proper nouns should be capitalized in body text. In general, strive to be

-as strict as possible in applying this rule. Avoid using capitals for emphasis

-or to denote "specialness".

-

-The word "Docker" should always be capitalized when referring to either the

-company or the technology. The only exception is when the term appears in a code

-sample.

-

-#### Starting sentences

-

-Because code samples should always be written exactly as they would appear

-on-screen, you should avoid starting sentences with a code sample.

-

-#### In headings

-

-Headings take sentence capitalization, meaning that only the first letter is

-capitalized (and words that would normally be capitalized in a sentence, e.g.,

-"Docker"). Do not use Title Case (i.e., capitalizing every word) for headings. Generally, we adhere to [AP style

-for titles](http://www.quickanddirtytips.com/education/grammar/capitalizing-titles).

-

-## Periods

-

-We prefer one space after a period at the end of a sentence, not two. 

-

-See [lists](#lists) below for how to punctuate list items.

-

-### Abbreviations and acronyms

-

-* Exempli gratia (e.g.) and id est ( i.e.): these should always have periods and

-are always followed by a comma.

-

-* Acronyms are pluralized by simply adding "s", e.g., PCs, OSs.

-

-* On first use on a given page, the complete term should be used, with the

-abbreviation or acronym in parentheses. E.g., Red Hat Enterprise Linux (RHEL).

-The exception is common, non-technical acronyms like AKA or ASAP. Note that

-acronyms other than i.e. and e.g. are capitalized.

-

-* Other than "e.g." and "i.e." (as discussed above), acronyms do not take

-periods, PC not P.C.

-

-

-### Lists

-

-When writing lists, keep the following in mind:

-

-Use bullets when the items being listed are independent of each other and the

-order of presentation is not important.

-

-Use numbers for steps that have to happen in order or if you have mentioned the

-list in introductory text. For example, if you wrote "There are three config

-settings available for SSL, as follows:", you would number each config setting

-in the subsequent list.

-

-In all lists, if an item is a complete sentence, it should end with a

-period. Otherwise, we prefer no terminal punctuation for list items.

-Each item in a list should start with a capital.

-

-### Numbers

-

-Write out numbers in body text and titles from one to ten. From 11 on, use numerals.

-

-### Notes

-

-Use notes sparingly and only to bring things to the reader's attention that are

-critical or otherwise deserving of being called out from the body text. Please

-format all notes as follows:

-

-    > **Note:**

-    > One line of note text

-    > another line of note text

-

-### Avoid excess use of "i.e."

-

-Minimize your use of "i.e.". It can add an unnecessary interpretive burden on

-the reader. Avoid writing "This is a thing, i.e., it is like this". Just

-say what it is: "This thing is …"

-

-### Preferred usages

-

-#### Login vs. log in. 

-

-A "login" is a noun (one word), as in "Enter your login". "Log in" is a compound

-verb (two words), as in "Log in to the terminal".

-

-### Oxford comma

-

-One way in which we differ from AP style is that Docker’s docs use the [Oxford

-comma](http://en.wikipedia.org/wiki/Serial_comma) in all cases. That’s our

-position on this controversial topic, we won't change our mind, and that’s that!

-

-### Code and UI text styling

-

-We require `code font` styling (monospace, sans-serif) for all text that refers

-to a command or other input or output from the CLI. This includes file paths

-(e.g., `/etc/hosts/docker.conf`). If you enclose text in backticks (`) markdown

-will style the text as code. 

-

-Text from a CLI should be quoted verbatim, even if it contains errors or its

-style contradicts this guide. You can add "(sic)" after the quote to indicate

-the errors are in the quote and are not errors in our docs.

-

-Text taken from a GUI (e.g., menu text or button text) should appear in "double

-quotes". The text should take the exact same capitalisation, etc. as appears in

-the GUI. E.g., Click "Continue" to save the settings.

-

-Text that refers to a keyboard command or hotkey is  capitalized (e.g., Ctrl-D).

-

-When writing CLI examples, give the user hints by making the examples resemble

-exactly what they see in their shell: 

-

-* Indent shell examples by 4 spaces so they get rendered as code blocks.

-* 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).

-

-Please test all code samples to ensure that they are correct and functional so

-that users can successfully cut-and-paste samples directly into the CLI.

-

-## Pull requests

-

-The pull request (PR) process is in place so that we can ensure changes made to

-the docs are the best changes possible. A good PR will do some or all of the

-following:

-

-* Explain why the change is needed

-* Point out potential issues or questions

-* Ask for help from experts in the company or the community

-* Encourage feedback from core developers and others involved in creating the

-software being documented.

-

-Writing a PR that is singular in focus and has clear objectives will encourage

-all of the above. Done correctly, the process allows reviewers (maintainers and

-community members) to validate the claims of the documentation and identify

-potential problems in communication or presentation. 

-

-### Commit messages

-

-In order to write clear, useful commit messages, please follow these

-[recommendations](http://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message).

-

-## Links

-

-For accessibility and usability reasons, avoid using phrases such as "click

-here" for link text. Recast your sentence so that the link text describes the

-content of the link, as we did in the

-["Commit messages" section](#commit-messages) above.

-

-You can use relative links (../linkeditem) to link to other pages in Docker's

-documentation.

-

-## Graphics

-

-When you need to add a graphic, try to make the file-size as small as possible.

-If you need help reducing file-size of a high-resolution image, feel free to

-contact us for help.

-Usually, graphics should go in the same directory as the .md file that

-references them, or in a subdirectory for images if one already exists.

-

-The preferred file format for graphics is PNG, but GIF and JPG are also

-acceptable. 

-

-If you are referring to a specific part of the UI in an image, use

-call-outs (circles and arrows or lines) to highlight what you’re referring to.

-Line width for call-outs should not exceed five pixels. The preferred color for

-call-outs is red.

-

-Be sure to include descriptive alt-text for the graphic. This greatly helps

-users with accessibility issues.

-

-Lastly, be sure you have permission to use any included graphics.

\ No newline at end of file

new file mode 100644

@@ -0,0 +1,13 @@

+# Project

+

+## Contents:

+

+- [README first](who-written-for)

+- [Set up prerequisites](set-up-prereqs/) 

+- [Work with a development container](set-up-dev-env/) 

+- [Run tests and test documentation](test-and-docs/)

+- [Make a project contribution](make-a-contribution/)

+- [Advanced contributing](advanced-contributing/)

+- [Where to get help](get-help/)

+- [Coding style guide](coding-style/)

+- [Documentation style guide](doc-style/)

\ No newline at end of file

new file mode 100644

@@ -0,0 +1,126 @@

+page_title: Advanced contributing

+page_description: Explains workflows for refactor and design proposals

+page_keywords: contribute, project, design, refactor, proposal

+

+# Advanced contributing

+

+In this section, you learn about the more advanced contributions you can make. They are advanced because they have a more involved workflow or require greater programming experience. Don't be scared off though, if you like to stretch and challenge yourself, this is the place for you.

+

+This section gives generalized instructions for advanced contributions. You'll read about the workflow but there are not specific descriptions of commands. Your goal should be to understand the processes described.

+

+At this point, you should have read and worked through the earlier parts of the project contributor guide. You should also have <a href="../make-a-contribution" target="_blank"> made at least one project contribution</a>.

+

+## Refactor or cleanup proposal

+

+A refactor or cleanup proposal changes Docker's internal structure without altering the external behavior. To make this type of proposal:

+

+1. Fork `docker/docker`.

+

+2. Make your changes in a feature branch.

+

+3. Sync and rebase with `master` as you work.

+

+3. Run the full test suite.

+

+4. Submit your code through a pull request (PR).

+

+	The PR's title should have the format:

+	

+	**Cleanup:** _short title_

+	

+	If your changes required logic changes, note that in your request.

+	

+5. Work through Docker's review process until merge.

+

+

+## Design proposal

+

+A design proposal solves a problem or adds a feature to the Docker software. The process for submitting design proposals requires two pull requests, one for the design and one for the implementation.

+

+![Simple process](/project/images/proposal.png)

+

+The important thing to notice is that both the design pull request and the implementation pull request go through a review. In other words, there is considerable time commitment in a design proposal; so, you might want to pair with someone on design work.

+

+The following provides greater detail on the process:

+

+1. Come up with an idea.

+

+	Ideas usually come from limitations users feel working with a product. So,

+	take some time to really use Docker. Try it on different platforms; explore

+	how it works with different web applications. Go to some community events

+	and find out what other users want.

+

+2. Review existing issues and proposals to make sure no other user is proposing a similar idea.

+

+    The design proposals are <a

+    href="https://github.com/docker/docker/pulls?q=is%3Aopen+is%3Apr+label%

+    3AProposal" target="_blank">all online in our GitHub pull requests</a>. 

+    

+3. Talk to the community about your idea.

+

+	We have lots of <a href="../get-help" target="_blank">community forums</a>

+	where you can get feedback on your idea. Float your idea in a forum or two

+	to get some commentary going on it.

+	

+4. Fork `docker/docker` and clone the repo to your local host.

+

+5. Create a new Markdown file in the area you wish to change.  

+

+	For example, if you want to redesign our daemon create a new file under the

+	`daemon/` folder. 

+

+6. Name the file descriptively, for example `redesign-daemon-proposal.md`.	

+	

+7. Write a proposal for your change into the file.

+

+	This is a markdown file that describes your idea. Your proposal

+	should include information like:

+	

+	* Why is this changed needed or what are the use cases?

+	* What are the requirements this change should meet?

+	* What are some ways to design/implement this feature?

+	* Which design/implementation do you think is best and why?

+	* What are the risks or limitations of your proposal?

+	

+	 This is your chance to convince people your idea is sound. 

+	  

+8. Submit your proposal in a pull request to `docker/docker`.

+

+	The title should have the format:

+	

+	**Proposal:** _short title_

+	

+	The body of the pull request should include a brief summary of your change

+	and then say something like "_See the file for a complete description_".

+	

+9. Refine your proposal through review.

+

+	The maintainers and the community review your proposal. You'll need to

+	answer questions and sometimes explain or defend your approach. This is

+	chance for everyone to both teach and learn.

+   

+10. Pull request accepted.

+

+	Your request may also be rejected. Not every idea is a good fit for Docker.

+	Let's assume though your proposal succeeded. 

+	

+11. Implement your idea.

+

+	Implementation uses all the standard practices of any contribution.

+	

+	 * fork `docker/docker`

+	 * create a feature branch

+	 * sync frequently back to master

+	 * test as you go and full test before a PR

+	 

+	 If you run into issues, the community is there to help.

+	 

+12. When you have a complete implementation, submit a pull request back to `docker/docker`.

+

+13. Review and iterate on your code.

+

+	If you are making a large code change, you can expect greater scrutiny

+	during this phase. 

+	

+14. Acceptance and merge!

+

new file mode 100644

@@ -0,0 +1,76 @@

+page_title: Coding Style Checklist

+page_description: List of guidelines for coding Docker contributions

+page_keywords: change, commit, squash, request, pull request, test, unit test, integration tests, Go, gofmt, LGTM

+

+# Coding Style Checklist

+

+This checklist summarizes the material you experienced working through [make a code contribution](/project/make-a-contribution) and [advanced contributing](/project/advanced-contributing).  The checklist applies to code that is program code or code that is documentation code.

+

+## Change and commit code

+

+* Fork the `docker/docker` repository.

+

+* Make changes on your fork in a feature branch. Name your branch `XXXX-something` where `XXXX` is the issue number you are working on.

+

+* Run `gofmt -s -w file.go` on each changed file before

+committing your changes. Most editors have plug-ins that do this automatically.

+

+* Update the documentation when creating or modifying features. 

+

+* Commits that fix or close an issue should reference them in the commit message

+`Closes #XXXX` or `Fixes #XXXX`. Mentions help by automatically closing the

+issue on a merge.

+

+* After every commit, run the test suite and ensure it is passing.

+

+* Sync and rebase frequently as you code to keep up with `docker` master.

+

+* Set your `git` signature and make sure you sign each commit.

+

+* Do not add yourself to the `AUTHORS` file. This file is autogenerated from the Git history.

+

+## Tests and testing

+

+* Submit unit tests for your changes. 

+

+* Make use of the builtin Go test framework built. 

+

+* Use existing Docker test files (`name_test.go`) for inspiration. 

+

+* Run <a href="../test-and-docs" target="_blank">the full test suite</a> on your branch before submitting a pull request.

+

+* Run `make docs` to build the documentation and then check it locally.

+

+* Use an <a href="http://www.hemingwayapp.com" target="_blank">online grammar

+checker</a> or similar to test you documentation changes for clarity, concision,

+and correctness.

+

+## Pull requests

+

+* Sync and cleanly rebase on top of Docker's `master` without multiple branches

+mixed into the PR.

+

+* Before the pull request, squash your commits into logical units of work using `git rebase -i` and `git push -f`. 

+

+* Include documentation changes in the same commit so that a revert would remove all traces of the feature or fix.

+

+* Reference each issue in your pull request description (`#XXXX`)

+

+## Respond to pull requests reviews 

+

+* Docker maintainers use LGTM (**l**ooks-**g**ood-**t**o-**m**e) in PR comments to indicate acceptance.

+

+* Code review comments may be added to your pull request. Discuss, then make the

+suggested modifications and push additional commits to your feature branch. 

+

+* Incorporate changes on your feature branch and push to your fork. This automatically updates your open pull request.

+

+* Post a comment after pushing to alert reviewers to PR changes; pushing a change does not send notifications.

+

+* A change requires LGTMs from an absolute majority maintainers of an affected component. For example, if you change `docs/` and `registry/` code, an absolute majority of the `docs/` and the `registry/` maintainers must approve your PR.

+

+## Merges after pull requests

+

+* After a merge, [a master build](https://master.dockerproject.com/) is available almost immediately. 

+

+* If you made a documentation change, you can see it at [docs.master.dockerproject.com](http://docs.master.dockerproject.com/). 

new file mode 100644

@@ -0,0 +1,276 @@

+page_title: Style Guide for Docker Documentation

+page_description: Style guide for Docker documentation describing standards and conventions for contributors

+page_keywords: style, guide, docker, documentation

+

+# Docker documentation: style & grammar conventions

+

+## Style standards

+

+Over time, different publishing communities have written standards for the style

+and grammar they prefer in their publications. These standards are called

+[style guides](http://en.wikipedia.org/wiki/Style_guide). Generally, Docker’s

+documentation uses the standards described in the

+[Associated Press's (AP) style guide](http://en.wikipedia.org/wiki/AP_Stylebook). 

+If a question about syntactical, grammatical, or lexical practice comes up,

+refer to the AP guide first. If you don’t have a copy of (or online subscription

+to) the AP guide, you can almost always find an answer to a specific question by

+searching the web. If you can’t find an answer, please ask a

+[maintainer](https://github.com/docker/docker/blob/master/docs/MAINTAINERS) and

+we will find the answer.

+

+That said, please don't get too hung up on using correct style. We'd rather have

+you submit good information that doesn't conform to the guide than no

+information at all. Docker's tech writers are always happy to help you with the

+prose, and we promise not to judge or use a red pen!

+

+> **Note:**

+> The documentation is written with paragraphs wrapped at 80 column lines to

+> make it easier for terminal use. You can probably set up your favorite text

+> editor to do this automatically for you.

+

+### Prose style

+

+In general, try to write simple, declarative prose. We prefer short,

+single-clause sentences and brief three-to-five sentence paragraphs. Try to

+choose vocabulary that is straightforward and precise. Avoid creating new terms,

+using obscure terms or, in particular, using a lot of jargon. For example, use

+"use" instead of leveraging "leverage".

+

+That said, don’t feel like you have to write for localization or for

+English-as-a-second-language (ESL) speakers specifically. Assume you are writing

+for an ordinary speaker of English with a basic university education. If your

+prose is simple, clear, and straightforward it will translate readily.

+

+One way to think about this is to assume Docker’s users are generally university

+educated and read at at least a "16th" grade level (meaning they have a

+university degree). You can use a [readability

+tester](https://readability-score.com/) to help guide your judgement. For

+example, the readability score for the phrase "Containers should be ephemeral"

+is around the 13th grade level (first year at university), and so is acceptable.

+

+In all cases, we prefer clear, concise communication over stilted, formal

+language. Don't feel like you have to write documentation that "sounds like

+technical writing."

+

+### Metaphor and figurative language

+

+One exception to the "don’t write directly for ESL" rule is to avoid the use of

+metaphor or other

+[figurative language](http://en.wikipedia.org/wiki/Literal_and_figurative_language) to

+describe things. There are too many cultural and social issues that can prevent

+a reader from correctly interpreting a metaphor.

+

+## Specific conventions

+

+Below are some specific recommendations (and a few deviations) from AP style

+that we use in our docs.

+

+### Contractions

+

+As long as your prose does not become too slangy or informal, it's perfectly

+acceptable to use contractions in our documentation. Make sure to use

+apostrophes correctly.

+

+### Use of dashes in a sentence.

+

+Dashes refers to the en dash (–) and the em dash (—). Dashes can be used to

+separate parenthetical material.

+

+Usage Example: This is an example of a Docker client – which uses the Big Widget

+to run – and does x, y, and z.

+

+Use dashes cautiously and consider whether commas or parentheses would work just

+as well. We always emphasize short, succinct sentences.

+

+More info from the always handy [Grammar Girl site](http://www.quickanddirtytips.com/education/grammar/dashes-parentheses-and-commas).

+

+### Pronouns

+

+It's okay to use first and second person pronouns. Specifically, use "we" to

+refer to Docker and "you" to refer to the user. For example, "We built the

+`exec` command so you can resize a TTY session."

+

+As much as possible, avoid using gendered pronouns ("he" and "she", etc.).

+Either recast the sentence so the pronoun is not needed or, less preferably,

+use "they" instead. If you absolutely can't get around using a gendered pronoun,

+pick one and stick to it. Which one you choose is up to you. One common

+convention is to use the pronoun of the author's gender, but if you prefer to

+default to "he" or "she", that's fine too.

+

+### Capitalization 

+

+#### In general

+

+Only proper nouns should be capitalized in body text. In general, strive to be

+as strict as possible in applying this rule. Avoid using capitals for emphasis

+or to denote "specialness".

+

+The word "Docker" should always be capitalized when referring to either the

+company or the technology. The only exception is when the term appears in a code

+sample.

+

+#### Starting sentences