GitHub PullRequestReviewCommentEvent at 2014-10-28 19:32:23
Repository: docker
Actor: jamtur01
Payload: {"action":"created","comment":{"url":"https://api.github.com/repos/docker/docker/pulls/comments/19497170","id":19497170,"diff_hunk":"@@ -0,0 +1,247 @@\n+page_title: Style Guide for Docker Documentation\n+page_description: Style guide for Docker documentation describing standards and conventions for contributors\n+page_keywords: style, guide, docker, documentation\n+\n+# Docker documentation: style & grammar conventions\n+\n+## Style standards\n+\n+Over time, different publishing communities have written standards for the style\n+and grammar they prefer in their publications. These standards are called\n+[style guides](http://en.wikipedia.org/wiki/Style_guide). Generally, Docker’s\n+documentation uses the standards described in the\n+[Associated Press's (AP) style guide](http://en.wikipedia.org/wiki/AP_Stylebook). \n+If a question about syntactical, grammatical, or lexical practice comes up,\n+refer to the AP guide first. If you don’t have a copy of (or online subscription\n+to) the AP guide, you can almost always find an answer to a specific question by\n+searching the web. If you can’t find an answer, please ask a\n+[maintainer](https://github.com/docker/docker/blob/master/docs/MAINTAINERS) and\n+we will find the answer.\n+\n+That said, please don't get too hung up on using correct style. We'd rather have\n+you submit good information that doesn't conform to the guide than no\n+information at all. Docker's tech writers are always happy to help you with the\n+prose, and we promise not to judge or use a red pen!\n+\n+> **Note:**\n+> The documentation is written with paragraphs wrapped at 80 column lines to\n+> make it easier for terminal use. You can probably set up your favorite text\n+> editor to do this automatically for you.\n+\n+### Prose style\n+\n+In general, try to write simple, declarative prose. We prefer short,\n+single-clause sentences and brief three-to-five sentence paragraphs. Try to\n+choose vocabulary that is straightforward and precise. Avoid creating new terms,\n+using obscure terms or, in particular, using a lot of jargon. For example, use\n+\"use\" instead of leveraging \"leverage\".\n+\n+That said, don’t feel like you have to write for localization or for ESL\n+speakers specifically. Assume you are writing for an ordinary speaker of English\n+with a basic college education. If your prose is simple, clear, and\n+straightforward it will translate readily.\n+\n+One way to think about this is to assume Docker’s users are generally college\n+educated and read at at least a \"16th\" grade level. You can use a [readability\n+tester](https://readability-score.com/) to help guide your judgement. For\n+example, the readability score for the phrase \"Containers should be ephemeral\"\n+is around the 13th grade level (college freshman), and so is acceptable.\n+\n+In all cases, we prefer clear, concise communication over stilted, formal\n+language. Don't feel like you have to write documentation that \"sounds like\n+technical writing.\"\n+\n+### Metaphor and figurative language\n+\n+One exception to the \"don’t write directly for ESL\" rule is to avoid the use of\n+metaphor or other\n+[figurative language](http://en.wikipedia.org/wiki/Literal_and_figurative_language) to\n+describe things. There are too many cultural and social issues that can prevent\n+a reader from correctly interpreting a metaphor.\n+\n+## Specific conventions\n+\n+Below are some specific recommendations (and a few deviations) from AP style\n+that we use in our docs.\n+\n+### Use of dashes in a sentence.\n+\n+Dashes refers to the en dash (–) and the em dash (—). Dashes can be used to\n+separate parenthetical material.\n+\n+Usage Example: This is an example of a Docker client – which uses the Big Widget\n+to run – and does x, y, and z.\n+\n+Use dashes cautiously and consider whether commas or parentheses would work just\n+as well. We always emphasize short, succinct sentences.\n+\n+More info from the always handy [Grammar Girl site](http://www.quickanddirtytips.com/education/grammar/dashes-parentheses-and-commas).\n+\n+### Pronouns\n+\n+It's okay to use first and second person pronouns. Specifically, use \"we\" to\n+refer to Docker and \"you\" to refer to the user. For example, \"We built the\n+`exec` command so you can resize a TTY session.\"\n+\n+As much as possible, avoid using gendered pronouns (\"he\" and \"she\", etc.).\n+Either recast the sentence so the pronoun is not needed or, less preferably,\n+use \"they\" instead. If you absolutely can't get around using a gendered pronoun,\n+pick one and stick to it. Which one you choose is up to you. One common\n+convention is to use the pronoun of the author's gender.\n+\n+### Capitalization \n+\n+#### In general\n+\n+Only proper nouns should be capitalized in body text. In general, strive to be\n+as strict as possible in applying this rule. Avoid using capitals for emphasis\n+or to denote \"specialness\".\n+\n+The word \"Docker\" should always be capitalized when referring to either the\n+company or the technology. The only exception is when the term appears in a code\n+sample.\n+\n+#### Starting sentences\n+\n+Because code samples should always be written exactly as they would appear\n+on-screen, you should avoid starting sentences with a code sample.\n+\n+#### In headings\n+\n+Headings take sentence capitalization, meaning that only the first letter is\n+capitalized (and words that would normally be capitalized in a sentence, e.g.,\n+\"Docker\"). Do not use Title Case for headings. Generally, we adhere to AP style\n+for titles. For more info, see:\n+http://www.quickanddirtytips.com/education/grammar/capitalizing-titles\n+\n+### Abbreviations and acronyms\n+\n+* Exempli gratia (e.g.) and id est ( i.e.): these should always have periods and\n+are always followed by a comma.\n+\n+* Acronyms are pluralized by simply adding \"s\", e.g., PCs, OSs.\n+\n+* On first use on a given page, the complete term should be used, with the\n+abbreviation or acronym in parentheses. E.g., Red Hat Enterprise Linux (RHEL).\n+The exception is common, non-technical acronyms like aka or asap.\n+\n+* Other than \"e.g.\" and \"i.e.\" (as discussed above), acronyms do not take periods, PC not P.C.\n+\n+\n+### Lists\n+\n+When writing lists, keep the following in mind:\n+\n+Use bullets when the items being listed are independant of each other and the\n+order of presentation is not important.\n+\n+Use numbers for steps that have to happen in order or if you have mentioned the\n+list in introductory text. For example, if you wrote \"There are three config\n+settings available for SSL, as follows:\", you would number each config setting\n+in the subsequent list.\n+\n+### Numbers\n+\n+Write out numbers from one to ten. From 11 on, use numerals.","path":"docs/sources/contributing/docs_style-guide.md","position":145,"original_position":145,"commit_id":"2ef676227d3070ff554afcd9744aeef4e3a4b7f4","original_commit_id":"2ef676227d3070ff554afcd9744aeef4e3a4b7f4","user":{"login":"jamtur01","id":4365,"avatar_url":"https://avatars.githubusercontent.com/u/4365?v=2","gravatar_id":"","url":"https://api.github.com/users/jamtur01","html_url":"https://github.com/jamtur01","followers_url":"https://api.github.com/users/jamtur01/followers","following_url":"https://api.github.com/users/jamtur01/following{/other_user}","gists_url":"https://api.github.com/users/jamtur01/gists{/gist_id}","starred_url":"https://api.github.com/users/jamtur01/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jamtur01/subscriptions","organizations_url":"https://api.github.com/users/jamtur01/orgs","repos_url":"https://api.github.com/users/jamtur01/repos","events_url":"https://api.github.com/users/jamtur01/events{/privacy}","received_events_url":"https://api.github.com/users/jamtur01/received_events","type":"User","site_admin":false},"body":"Perhaps add a \"In body text\" so people aren't confused by the list reference above.","created_at":"2014-10-28T19:32:23Z","updated_at":"2014-10-28T19:32:23Z","html_url":"https://github.com/docker/docker/pull/8500#discussion_r19497170","pull_request_url":"https://api.github.com/repos/docker/docker/pulls/8500","_links":{"self":{"href":"https://api.github.com/repos/docker/docker/pulls/comments/19497170"},"html":{"href":"https://github.com/docker/docker/pull/8500#discussion_r19497170"},"pull_request":{"href":"https://api.github.com/repos/docker/docker/pulls/8500"}}},"pull_request":{"url":"https://api.github.com/repos/docker/docker/pulls/8500","id":22534897,"html_url":"https://github.com/docker/docker/pull/8500","diff_url":"https://github.com/docker/docker/pull/8500.diff","patch_url":"https://github.com/docker/docker/pull/8500.patch","issue_url":"https://api.github.com/repos/docker/docker/issues/8500","number":8500,"state":"open","locked":false,"title":"Adds new Docs Style Guide.","user":{"login":"fredlf","id":1459582,"avatar_url":"https://avatars.githubusercontent.com/u/1459582?v=2","gravatar_id":"","url":"https://api.github.com/users/fredlf","html_url":"https://github.com/fredlf","followers_url":"https://api.github.com/users/fredlf/followers","following_url":"https://api.github.com/users/fredlf/following{/other_user}","gists_url":"https://api.github.com/users/fredlf/gists{/gist_id}","starred_url":"https://api.github.com/users/fredlf/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/fredlf/subscriptions","organizations_url":"https://api.github.com/users/fredlf/orgs","repos_url":"https://api.github.com/users/fredlf/repos","events_url":"https://api.github.com/users/fredlf/events{/privacy}","received_events_url":"https://api.github.com/users/fredlf/received_events","type":"User","site_admin":false},"body":"Adds a new style guide for docs. This is meant to be the definitive reference for all questions of how to write and style our docs. Includes changes to mkdocs yml and moves style info from docs README, adding a link instead. Made a couple edits to the README too, while I was in there.","created_at":"2014-10-10T01:14:56Z","updated_at":"2014-10-28T19:32:23Z","closed_at":null,"merged_at":null,"merge_commit_sha":"4a3c07c6c5d45e4c23741a9706bda6506a66230d","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/docker/docker/pulls/8500/commits","review_comments_url":"https://api.github.com/repos/docker/docker/pulls/8500/comments","review_comment_url":"https://api.github.com/repos/docker/docker/pulls/comments/{number}","comments_url":"https://api.github.com/repos/docker/docker/issues/8500/comments","statuses_url":"https://api.github.com/repos/docker/docker/statuses/2ef676227d3070ff554afcd9744aeef4e3a4b7f4","head":{"label":"fredlf:style-guide","ref":"style-guide","sha":"2ef676227d3070ff554afcd9744aeef4e3a4b7f4","user":{"login":"fredlf","id":1459582,"avatar_url":"https://avatars.githubusercontent.com/u/1459582?v=2","gravatar_id":"","url":"https://api.github.com/users/fredlf","html_url":"https://github.com/fredlf","followers_url":"https://api.github.com/users/fredlf/followers","following_url":"https://api.github.com/users/fredlf/following{/other_user}","gists_url":"https://api.github.com/users/fredlf/gists{/gist_id}","starred_url":"https://api.github.com/users/fredlf/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/fredlf/subscriptions","organizations_url":"https://api.github.com/users/fredlf/orgs","repos_url":"https://api.github.com/users/fredlf/repos","events_url":"https://api.github.com/users/fredlf/events{/privacy}","received_events_url":"https://api.github.com/users/fredlf/received_events","type":"User","site_admin":false},"repo":{"id":20460509,"name":"docker","full_name":"fredlf/docker","owner":{"login":"fredlf","id":1459582,"avatar_url":"https://avatars.githubusercontent.com/u/1459582?v=2","gravatar_id":"","url":"https://api.github.com/users/fredlf","html_url":"https://github.com/fredlf","followers_url":"https://api.github.com/users/fredlf/followers","following_url":"https://api.github.com/users/fredlf/following{/other_user}","gists_url":"https://api.github.com/users/fredlf/gists{/gist_id}","starred_url":"https://api.github.com/users/fredlf/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/fredlf/subscriptions","organizations_url":"https://api.github.com/users/fredlf/orgs","repos_url":"https://api.github.com/users/fredlf/repos","events_url":"https://api.github.com/users/fredlf/events{/privacy}","received_events_url":"https://api.github.com/users/fredlf/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/fredlf/docker","description":"Docker - the open-source application container engine","fork":true,"url":"https://api.github.com/repos/fredlf/docker","forks_url":"https://api.github.com/repos/fredlf/docker/forks","keys_url":"https://api.github.com/repos/fredlf/docker/keys{/key_id}","collaborators_url":"https://api.github.com/repos/fredlf/docker/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/fredlf/docker/teams","hooks_url":"https://api.github.com/repos/fredlf/docker/hooks","issue_events_url":"https://api.github.com/repos/fredlf/docker/issues/events{/number}","events_url":"https://api.github.com/repos/fredlf/docker/events","assignees_url":"https://api.github.com/repos/fredlf/docker/assignees{/user}","branches_url":"https://api.github.com/repos/fredlf/docker/branches{/branch}","tags_url":"https://api.github.com/repos/fredlf/docker/tags","blobs_url":"https://api.github.com/repos/fredlf/docker/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/fredlf/docker/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/fredlf/docker/git/refs{/sha}","trees_url":"https://api.github.com/repos/fredlf/docker/git/trees{/sha}","statuses_url":"https://api.github.com/repos/fredlf/docker/statuses/{sha}","languages_url":"https://api.github.com/repos/fredlf/docker/languages","stargazers_url":"https://api.github.com/repos/fredlf/docker/stargazers","contributors_url":"https://api.github.com/repos/fredlf/docker/contributors","subscribers_url":"https://api.github.com/repos/fredlf/docker/subscribers","subscription_url":"https://api.github.com/repos/fredlf/docker/subscription","commits_url":"https://api.github.com/repos/fredlf/docker/commits{/sha}","git_commits_url":"https://api.github.com/repos/fredlf/docker/git/commits{/sha}","comments_url":"https://api.github.com/repos/fredlf/docker/comments{/number}","issue_comment_url":"https://api.github.com/repos/fredlf/docker/issues/comments/{number}","contents_url":"https://api.github.com/repos/fredlf/docker/contents/{+path}","compare_url":"https://api.github.com/repos/fredlf/docker/compare/{base}...{head}","merges_url":"https://api.github.com/repos/fredlf/docker/merges","archive_url":"https://api.github.com/repos/fredlf/docker/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/fredlf/docker/downloads","issues_url":"https://api.github.com/repos/fredlf/docker/issues{/number}","pulls_url":"https://api.github.com/repos/fredlf/docker/pulls{/number}","milestones_url":"https://api.github.com/repos/fredlf/docker/milestones{/number}","notifications_url":"https://api.github.com/repos/fredlf/docker/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/fredlf/docker/labels{/name}","releases_url":"https://api.github.com/repos/fredlf/docker/releases{/id}","created_at":"2014-06-03T21:32:45Z","updated_at":"2014-07-24T21:22:49Z","pushed_at":"2014-10-28T18:55:03Z","git_url":"git://github.com/fredlf/docker.git","ssh_url":"git@github.com:fredlf/docker.git","clone_url":"https://github.com/fredlf/docker.git","svn_url":"https://github.com/fredlf/docker","homepage":"http://www.docker.io","size":36041,"stargazers_count":0,"watchers_count":0,"language":"Go","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"docker:master","ref":"master","sha":"248ec5d74e4f33bbcf946609fc5f9081a267fb8b","user":{"login":"docker","id":5429470,"avatar_url":"https://avatars.githubusercontent.com/u/5429470?v=2","gravatar_id":"","url":"https://api.github.com/users/docker","html_url":"https://github.com/docker","followers_url":"https://api.github.com/users/docker/followers","following_url":"https://api.github.com/users/docker/following{/other_user}","gists_url":"https://api.github.com/users/docker/gists{/gist_id}","starred_url":"https://api.github.com/users/docker/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/docker/subscriptions","organizations_url":"https://api.github.com/users/docker/orgs","repos_url":"https://api.github.com/users/docker/repos","events_url":"https://api.github.com/users/docker/events{/privacy}","received_events_url":"https://api.github.com/users/docker/received_events","type":"Organization","site_admin":false},"repo":{"id":7691631,"name":"docker","full_name":"docker/docker","owner":{"login":"docker","id":5429470,"avatar_url":"https://avatars.githubusercontent.com/u/5429470?v=2","gravatar_id":"","url":"https://api.github.com/users/docker","html_url":"https://github.com/docker","followers_url":"https://api.github.com/users/docker/followers","following_url":"https://api.github.com/users/docker/following{/other_user}","gists_url":"https://api.github.com/users/docker/gists{/gist_id}","starred_url":"https://api.github.com/users/docker/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/docker/subscriptions","organizations_url":"https://api.github.com/users/docker/orgs","repos_url":"https://api.github.com/users/docker/repos","events_url":"https://api.github.com/users/docker/events{/privacy}","received_events_url":"https://api.github.com/users/docker/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/docker/docker","description":"Docker - the open-source application container engine","fork":false,"url":"https://api.github.com/repos/docker/docker","forks_url":"https://api.github.com/repos/docker/docker/forks","keys_url":"https://api.github.com/repos/docker/docker/keys{/key_id}","collaborators_url":"https://api.github.com/repos/docker/docker/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/docker/docker/teams","hooks_url":"https://api.github.com/repos/docker/docker/hooks","issue_events_url":"https://api.github.com/repos/docker/docker/issues/events{/number}","events_url":"https://api.github.com/repos/docker/docker/events","assignees_url":"https://api.github.com/repos/docker/docker/assignees{/user}","branches_url":"https://api.github.com/repos/docker/docker/branches{/branch}","tags_url":"https://api.github.com/repos/docker/docker/tags","blobs_url":"https://api.github.com/repos/docker/docker/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/docker/docker/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/docker/docker/git/refs{/sha}","trees_url":"https://api.github.com/repos/docker/docker/git/trees{/sha}","statuses_url":"https://api.github.com/repos/docker/docker/statuses/{sha}","languages_url":"https://api.github.com/repos/docker/docker/languages","stargazers_url":"https://api.github.com/repos/docker/docker/stargazers","contributors_url":"https://api.github.com/repos/docker/docker/contributors","subscribers_url":"https://api.github.com/repos/docker/docker/subscribers","subscription_url":"https://api.github.com/repos/docker/docker/subscription","commits_url":"https://api.github.com/repos/docker/docker/commits{/sha}","git_commits_url":"https://api.github.com/repos/docker/docker/git/commits{/sha}","comments_url":"https://api.github.com/repos/docker/docker/comments{/number}","issue_comment_url":"https://api.github.com/repos/docker/docker/issues/comments/{number}","contents_url":"https://api.github.com/repos/docker/docker/contents/{+path}","compare_url":"https://api.github.com/repos/docker/docker/compare/{base}...{head}","merges_url":"https://api.github.com/repos/docker/docker/merges","archive_url":"https://api.github.com/repos/docker/docker/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/docker/docker/downloads","issues_url":"https://api.github.com/repos/docker/docker/issues{/number}","pulls_url":"https://api.github.com/repos/docker/docker/pulls{/number}","milestones_url":"https://api.github.com/repos/docker/docker/milestones{/number}","notifications_url":"https://api.github.com/repos/docker/docker/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/docker/docker/labels{/name}","releases_url":"https://api.github.com/repos/docker/docker/releases{/id}","created_at":"2013-01-18T18:10:57Z","updated_at":"2014-10-28T18:53:49Z","pushed_at":"2014-10-28T00:58:54Z","git_url":"git://github.com/docker/docker.git","ssh_url":"git@github.com:docker/docker.git","clone_url":"https://github.com/docker/docker.git","svn_url":"https://github.com/docker/docker","homepage":"http://www.docker.com","size":152945,"stargazers_count":16106,"watchers_count":16106,"language":"Go","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":3134,"mirror_url":null,"open_issues_count":846,"forks":3134,"open_issues":846,"watchers":16106,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/docker/docker/pulls/8500"},"html":{"href":"https://github.com/docker/docker/pull/8500"},"issue":{"href":"https://api.github.com/repos/docker/docker/issues/8500"},"comments":{"href":"https://api.github.com/repos/docker/docker/issues/8500/comments"},"review_comments":{"href":"https://api.github.com/repos/docker/docker/pulls/8500/comments"},"review_comment":{"href":"https://api.github.com/repos/docker/docker/pulls/comments/{number}"},"commits":{"href":"https://api.github.com/repos/docker/docker/pulls/8500/commits"},"statuses":{"href":"https://api.github.com/repos/docker/docker/statuses/2ef676227d3070ff554afcd9744aeef4e3a4b7f4"}}}}