1. docker
  2. Commit 461d33eeb0fe1058c9fcea39124c2d1f9e141765
Browse code

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)

Fred Lifton authored on 2014/10/30 08:43:18
Showing 3 changed files
docs/README.md
History View file @ 461d33e
... ... 
@@ -11,9 +11,8 @@ development) branch maps to the "master" documentation.
11 11
12 12 
 ## Contributing
13 13
14 
-- Follow the contribution guidelines ([see
15 
-  `../CONTRIBUTING.md`](../CONTRIBUTING.md)).
16 
-- [Remember to sign your work!](../CONTRIBUTING.md#sign-your-work)
14 
+Be sure to follow the [contribution guidelines](../CONTRIBUTING.md)).
15 
+In particular, [remember to sign your work!](../CONTRIBUTING.md#sign-your-work)
17 16
18 17 
 ## Getting Started
19 18
... ... 
@@ -41,26 +40,10 @@ to the menu definition in the `docs/mkdocs.yml` file.
41 41
42 42 
 ## Style guide
43 43
44 
-The documentation is written with paragraphs wrapped at 80 column lines to make
45 
-it easier for terminal use.
46 
-
47 
-### Examples
48 
-
49 
-When writing examples, give the user hints by making them resemble what they see
50 
-in their shell:
51 
-
52 
-- Indent shell examples by 4 spaces so they get rendered as code.
53 
-- Start typed commands with `$ ` (dollar space), so that they are easily
54 
-  differentiated from program output.
55 
-- Program output has no prefix.
56 
-- Comments begin with `# ` (hash space).
57 
-- In-container shell commands begin with `$$ ` (dollar dollar space).
58 
-
59 
-### Images
60 
-
61 
-When you need to add images, try to make them as small as possible (e.g., as
62 
-gifs). Usually images should go in the same directory as the `.md` file which
63 
-references them, or in a subdirectory if one already exists.
44 
+If you have questions about how to write for Docker's documentation (e.g.,
45 
+questions about grammar, syntax, formatting, styling, language, or tone) please
46 
+see the [style guide](sources/contributing/docs_style-guide.md). If something
47 
+isn't clear in the guide, please submit a PR to help us improve it.
64 48
65 49 
 ## Working using GitHub's file editor
66 50
... ... 
@@ -73,11 +56,11 @@ work!](../CONTRIBUTING.md#sign-your-work)
73 73
74 74 
 ## Branches
75 75
76 
-**There are two branches related to editing docs**: `master` and a `docs`
77 
-branch. You should always edit the documentation on a local branch of the `master`
76 
+**There are two branches related to editing docs**: `master` and `docs`. You
77 
+should always edit the documentation on a local branch of the `master`
78 78 
 branch, and send a PR against `master`.
79 79
80 
-That way your edits will automatically get included in later releases, and docs
80 
+That way your fixes will automatically get included in later releases, and docs
81 81 
 maintainers can easily cherry-pick your changes into the `docs` release branch.
82 82 
 In the rare case where your change is not forward-compatible, you may need to
83 83 
 base your changes on the `docs` branch.
... ... 
@@ -95,8 +78,10 @@ found between Docker code releases.
95 95
96 96 
 ## Publishing Documentation
97 97
98 
-To publish a copy of the documentation you need to have Docker up and running on your
99 
-machine. You'll also need a `docs/awsconfig` file containing AWS settings to deploy to.
98 
+To publish a copy of the documentation you need to have Docker up and running on
99 
+your machine. You'll also need a `docs/awsconfig` file containing the settings
100 
+you need to access the AWS bucket you'll be deploying to.
101 
+
100 102 
 The release script will create an s3 if needed, and will then push the files to it.
101 103
102 104 
     [profile dowideit-docs] aws_access_key_id = IHOIUAHSIDH234rwf....
... ... 
@@ -115,7 +100,8 @@ also update the root docs pages by running
115 115
116 116 
     make AWS_S3_BUCKET=dowideit-docs BUILD_ROOT=yes docs-release
117 117
118 
-> **Note:** if you are using Boot2Docker on OSX and the above command returns an error,
118 
+> **Note:**
119 
+> if you are using Boot2Docker on OSX and the above command returns an error,
119 120 
 > `Post http:///var/run/docker.sock/build?rm=1&t=docker-docs%3Apost-1.2.0-docs_update-2:
120 121 
 > dial unix /var/run/docker.sock: no such file or directory', you need to set the Docker
121 122 
 > host. Run `$(boot2docker shellinit)` to see the correct variable to set. The command
docs/mkdocs.yml
History View file @ 461d33e
... ... 
@@ -148,3 +148,4 @@ pages:
148 148 
 - ['contributing/index.md', '**HIDDEN**']
149 149 
 - ['contributing/contributing.md', 'Contribute', 'Contributing']
150 150 
 - ['contributing/devenvironment.md', 'Contribute', 'Development environment']
151 
+- ['contributing/docs_style-guide.md', 'Contribute', 'Documentation style guide']
docs/sources/contributing/docs_style-guide.md
History View file @ 461d33e
151 152 
new file mode 100644
... ... 
@@ -0,0 +1,276 @@
0 
+page_title: Style Guide for Docker Documentation
1 
+page_description: Style guide for Docker documentation describing standards and conventions for contributors
2 
+page_keywords: style, guide, docker, documentation
3 
+
4 
+# Docker documentation: style & grammar conventions
5 
+
6 
+## Style standards
7 
+
8 
+Over time, different publishing communities have written standards for the style
9 
+and grammar they prefer in their publications. These standards are called
10 
+[style guides](http://en.wikipedia.org/wiki/Style_guide). Generally, Docker’s
11 
+documentation uses the standards described in the
12 
+[Associated Press's (AP) style guide](http://en.wikipedia.org/wiki/AP_Stylebook).
13 
+If a question about syntactical, grammatical, or lexical practice comes up,
14 
+refer to the AP guide first. If you don’t have a copy of (or online subscription
15 
+to) the AP guide, you can almost always find an answer to a specific question by
16 
+searching the web. If you can’t find an answer, please ask a
17 
+[maintainer](https://github.com/docker/docker/blob/master/docs/MAINTAINERS) and
18 
+we will find the answer.
19 
+
20 
+That said, please don't get too hung up on using correct style. We'd rather have
21 
+you submit good information that doesn't conform to the guide than no
22 
+information at all. Docker's tech writers are always happy to help you with the
23 
+prose, and we promise not to judge or use a red pen!
24 
+
25 
+> **Note:**
26 
+> The documentation is written with paragraphs wrapped at 80 column lines to
27 
+> make it easier for terminal use. You can probably set up your favorite text
28 
+> editor to do this automatically for you.
29 
+
30 
+### Prose style
31 
+
32 
+In general, try to write simple, declarative prose. We prefer short,
33 
+single-clause sentences and brief three-to-five sentence paragraphs. Try to
34 
+choose vocabulary that is straightforward and precise. Avoid creating new terms,
35 
+using obscure terms or, in particular, using a lot of jargon. For example, use
36 
+"use" instead of leveraging "leverage".
37 
+
38 
+That said, don’t feel like you have to write for localization or for
39 
+English-as-a-second-language (ESL) speakers specifically. Assume you are writing
40 
+for an ordinary speaker of English with a basic university education. If your
41 
+prose is simple, clear, and straightforward it will translate readily.
42 
+
43 
+One way to think about this is to assume Docker’s users are generally university
44 
+educated and read at at least a "16th" grade level (meaning they have a
45 
+university degree). You can use a [readability
46 
+tester](https://readability-score.com/) to help guide your judgement. For
47 
+example, the readability score for the phrase "Containers should be ephemeral"
48 
+is around the 13th grade level (first year at university), and so is acceptable.
49 
+
50 
+In all cases, we prefer clear, concise communication over stilted, formal
51 
+language. Don't feel like you have to write documentation that "sounds like
52 
+technical writing."
53 
+
54 
+### Metaphor and figurative language
55 
+
56 
+One exception to the "don’t write directly for ESL" rule is to avoid the use of
57 
+metaphor or other
58 
+[figurative language](http://en.wikipedia.org/wiki/Literal_and_figurative_language) to
59 
+describe things. There are too many cultural and social issues that can prevent
60 
+a reader from correctly interpreting a metaphor.
61 
+
62 
+## Specific conventions
63 
+
64 
+Below are some specific recommendations (and a few deviations) from AP style
65 
+that we use in our docs.
66 
+
67 
+### Contractions
68 
+
69 
+As long as your prose does not become too slangy or informal, it's perfectly
70 
+acceptable to use contractions in our documentation. Make sure to use
71 
+apostrophes correctly.
72 
+
73 
+### Use of dashes in a sentence.
74 
+
75 
+Dashes refers to the en dash (–) and the em dash (—). Dashes can be used to
76 
+separate parenthetical material.
77 
+
78 
+Usage Example: This is an example of a Docker client – which uses the Big Widget
79 
+to run – and does x, y, and z.
80 
+
81 
+Use dashes cautiously and consider whether commas or parentheses would work just
82 
+as well. We always emphasize short, succinct sentences.
83 
+
84 
+More info from the always handy [Grammar Girl site](http://www.quickanddirtytips.com/education/grammar/dashes-parentheses-and-commas).
85 
+
86 
+### Pronouns
87 
+
88 
+It's okay to use first and second person pronouns. Specifically, use "we" to
89 
+refer to Docker and "you" to refer to the user. For example, "We built the
90 
+`exec` command so you can resize a TTY session."
91 
+
92 
+As much as possible, avoid using gendered pronouns ("he" and "she", etc.).
93 
+Either recast the sentence so the pronoun is not needed or, less preferably,
94 
+use "they" instead. If you absolutely can't get around using a gendered pronoun,
95 
+pick one and stick to it. Which one you choose is up to you. One common
96 
+convention is to use the pronoun of the author's gender, but if you prefer to
97 
+default to "he" or "she", that's fine too.
98 
+
99 
+### Capitalization
100 
+
101 
+#### In general
102 
+
103 
+Only proper nouns should be capitalized in body text. In general, strive to be
104 
+as strict as possible in applying this rule. Avoid using capitals for emphasis
105 
+or to denote "specialness".
106 
+
107 
+The word "Docker" should always be capitalized when referring to either the
108 
+company or the technology. The only exception is when the term appears in a code
109 
+sample.
110 
+
111 
+#### Starting sentences
112 
+
113 
+Because code samples should always be written exactly as they would appear
114 
+on-screen, you should avoid starting sentences with a code sample.
115 
+
116 
+#### In headings
117 
+
118 
+Headings take sentence capitalization, meaning that only the first letter is
119 
+capitalized (and words that would normally be capitalized in a sentence, e.g.,
120 
+"Docker"). Do not use Title Case (i.e., capitalizing every word) for headings. Generally, we adhere to [AP style
121 
+for titles](http://www.quickanddirtytips.com/education/grammar/capitalizing-titles).
122 
+
123 
+## Periods
124 
+
125 
+We prefer one space after a period at the end of a sentence, not two.
126 
+
127 
+See [lists](#lists) below for how to punctuate list items.
128 
+
129 
+### Abbreviations and acronyms
130 
+
131 
+* Exempli gratia (e.g.) and id est ( i.e.): these should always have periods and
132 
+are always followed by a comma.
133 
+
134 
+* Acronyms are pluralized by simply adding "s", e.g., PCs, OSs.
135 
+
136 
+* On first use on a given page, the complete term should be used, with the
137 
+abbreviation or acronym in parentheses. E.g., Red Hat Enterprise Linux (RHEL).
138 
+The exception is common, non-technical acronyms like AKA or ASAP. Note that
139 
+acronyms other than i.e. and e.g. are capitalized.
140 
+
141 
+* Other than "e.g." and "i.e." (as discussed above), acronyms do not take
142 
+periods, PC not P.C.
143 
+
144 
+
145 
+### Lists
146 
+
147 
+When writing lists, keep the following in mind:
148 
+
149 
+Use bullets when the items being listed are independant of each other and the
150 
+order of presentation is not important.
151 
+
152 
+Use numbers for steps that have to happen in order or if you have mentioned the
153 
+list in introductory text. For example, if you wrote "There are three config
154 
+settings available for SSL, as follows:", you would number each config setting
155 
+in the subsequent list.
156 
+
157 
+In all lists, if an item is a complete sentence, it should end with a
158 
+period. Otherwise, we prefer no terminal punctuation for list items.
159 
+Each item in a list should start with a capital.
160 
+
161 
+### Numbers
162 
+
163 
+Write out numbers in body text and titles from one to ten. From 11 on, use numerals.
164 
+
165 
+### Notes
166 
+
167 
+Use notes sparingly and only to bring things to the reader's attention that are
168 
+critical or otherwise deserving of being called out from the body text. Please
169 
+format all notes as follows:
170 
+
171 
+    **Note:**
172 
+    > One line of note text
173 
+    > another line of note text
174 
+
175 
+### Avoid excess use of "i.e."
176 
+
177 
+Minimize your use of "i.e.". It can add an unnecessary interpretive burden on
178 
+the reader. Avoid writing "This is a thing, i.e., it is like this". Just
179 
+say what it is: "This thing is …"
180 
+
181 
+### Preferred usages
182 
+
183 
+#### Login vs. log in.
184 
+
185 
+A "login" is a noun (one word), as in "Enter your login". "Log in" is a compound
186 
+verb (two words), as in "Log in to the terminal".
187 
+
188 
+### Oxford comma
189 
+
190 
+One way in which we differ from AP style is that Docker’s docs use the [Oxford
191 
+comma](http://en.wikipedia.org/wiki/Serial_comma) in all cases. That’s our
192 
+position on this controversial topic, we won't change our mind, and that’s that!
193 
+
194 
+### Code and UI text styling
195 
+
196 
+We require `code font` styling (monospace, sans-serif) for all text that refers
197 
+to a command or other input or output from the CLI. This includes file paths
198 
+(e.g., `/etc/hosts/docker.conf`). If you enclose text in backticks (`) markdown
199 
+will style the text as code.
200 
+
201 
+Text from a CLI should be quoted verbatim, even if it contains errors or its
202 
+style contradicts this guide. You can add "(sic)" after the quote to indicate
203 
+the errors are in the quote and are not errors in our docs.
204 
+
205 
+Text taken from a GUI (e.g., menu text or button text) should appear in "double
206 
+quotes". The text should take the exact same capitalisation, etc. as appears in
207 
+the GUI. E.g., Click "Continue" to save the settings.
208 
+
209 
+Text that refers to a keyboard command or hotkey is  capitalized (e.g., Ctrl-D).
210 
+
211 
+When writing CLI examples, give the user hints by making the examples resemble
212 
+exactly what they see in their shell:
213 
+
214 
+* Indent shell examples by 4 spaces so they get rendered as code blocks.
215 
+* Start typed commands with `$ ` (dollar space), so that they are easily
216 
+differentiated from program output.
217 
+* Program output has no prefix.
218 
+* Comments begin with # (hash space).
219 
+* In-container shell commands, begin with `$$ ` (dollar dollar space).
220 
+
221 
+Please test all code samples to ensure that they are correct and functional so
222 
+that users can successfully cut-and-paste samples directly into the CLI.
223 
+
224 
+## Pull requests
225 
+
226 
+The pull request (PR) process is in place so that we can ensure changes made to
227 
+the docs are the best changes possible. A good PR will do some or all of the
228 
+following:
229 
+
230 
+* Explain why the change is needed
231 
+* Point out potential issues or questions
232 
+* Ask for help from experts in the company or the community
233 
+* Encourage feedback from core developers and others involved in creating the
234 
+software being documented.
235 
+
236 
+Writing a PR that is singular in focus and has clear objectives will encourage
237 
+all of the above. Done correctly, the process allows reviewers (maintainers and
238 
+community members) to validate the claims of the documentation and identify
239 
+potential problems in communication or presentation.
240 
+
241 
+### Commit messages
242 
+
243 
+In order to write clear, useful commit messages, please follow these
244 
+[recommendations](http://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message).
245 
+
246 
+## Links
247 
+
248 
+For accessibility and usability reasons, avoid using phrases such as "click
249 
+here" for link text. Recast your sentence so that the link text describes the
250 
+content of the link, as we did in the
251 
+["Commit messages" section](#commit-messages) above.
252 
+
253 
+You can use relative links (../linkeditem) to link to other pages in Docker's
254 
+documentation.
255 
+
256 
+## Graphics
257 
+
258 
+When you need to add a graphic, try to make the file-size as small as possible.
259 
+If you need help reducing file-size of a high-resolution image, feel free to
260 
+contact us for help.
261 
+Usually, graphics should go in the same directory as the .md file that
262 
+references them, or in a subdirectory for images if one already exists.
263 
+
264 
+The preferred file format for graphics is PNG, but GIF and JPG are also
265 
+acceptable.
266 
+
267 
+If you are referring to a specific part of the UI in an image, use
268 
+call-outs (circles and arrows or lines) to highlight what you’re referring to.
269 
+Line width for call-outs should not exceed five pixels. The preferred color for
270 
+call-outs is red.
271 
+
272 
+Be sure to include descriptive alt-text for the graphic. This greatly helps
273 
+users with accessibility issues.
274 
+
275 
+Lastly, be sure you have permission to use any included graphics.
0 276 
\ No newline at end of file