diff --git a/.github/vale/Docker/Adverbs.yml b/.github/vale/Docker/Adverbs.yml index 630a31698b..753f36cecc 100644 --- a/.github/vale/Docker/Adverbs.yml +++ b/.github/vale/Docker/Adverbs.yml @@ -39,7 +39,6 @@ tokens: - crossly - cruelly - curiously - - currently - daintily - dearly - deceivingly diff --git a/.github/vale/Docker/Avoid.yml b/.github/vale/Docker/Avoid.yml new file mode 100644 index 0000000000..13f4b5ffc6 --- /dev/null +++ b/.github/vale/Docker/Avoid.yml @@ -0,0 +1,6 @@ +extends: existence +message: "Consider removing '%s'." +ignorecase: true +level: warning +tokens: + - Please \ No newline at end of file diff --git a/.github/vale/Docker/Contractions.yml b/.github/vale/Docker/Contractions.yml index c378035da6..54b1af1c36 100644 --- a/.github/vale/Docker/Contractions.yml +++ b/.github/vale/Docker/Contractions.yml @@ -1,7 +1,7 @@ extends: substitution message: "Consider using '%s' instead of '%s'." level: warning -ignorecase: true +ignorecase: false action: name: replace swap: @@ -10,6 +10,7 @@ swap: could not: couldn't did not: didn't do not: don't + Do not: Don't does not: doesn't has not: hasn't have not: haven't diff --git a/.github/vale/Docker/Currently.yml b/.github/vale/Docker/Currently.yml new file mode 100644 index 0000000000..a03d983052 --- /dev/null +++ b/.github/vale/Docker/Currently.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Avoid using words like '%s', the docs should describe the product as is." +link: https://docs.docker.com/contribute/style/recommended-words/ +level: warning +ignorecase: true +tokens: + - At this time + - Currently \ No newline at end of file diff --git a/.github/vale/Docker/Substitute.yml b/.github/vale/Docker/Substitute.yml index 6dd93b3f0e..fc9afb129b 100644 --- a/.github/vale/Docker/Substitute.yml +++ b/.github/vale/Docker/Substitute.yml @@ -6,12 +6,9 @@ level: suggestion action: name: replace swap: - '\b(?:eg|e\.g\.)[\s,]': for example - '\b(?:ie|i\.e\.)[\s,]': that is - (?:sign on|log on|log in): sign in above: previous adaptor: adapter - account name: username + (?:account name|accountname|user name): username administrate: administer admin: administrator afterwards: afterward @@ -27,22 +24,29 @@ swap: assembler: assembly language below: following check box: checkbox + check boxes: checkboxes click: select deselect: clear disable: turn off|toggle off + (?:drop down|dropdown): drop-down + '\b(?:eg|e\.g\.)[\s,]': for example enable: turn on|toggle on ergo: therefore - execute: invoke + execute: run gb: GB gbps: Gbps + '\b(?:ie|i\.e\.)[\s,]': that is kb: KB keypress: keystroke + (?:log out|logout): sign out mb: MB mutices: mutexes paas: PaaS pb: PB repo: repository scroll: navigate + (?:sign on|log on|log in|logon|login): sign in sign up: register tb: TB + vs: versus wish: want diff --git a/.github/vale/Docker/Terminology.yml b/.github/vale/Docker/Terminology.yml index b08ab9f600..685fccd721 100644 --- a/.github/vale/Docker/Terminology.yml +++ b/.github/vale/Docker/Terminology.yml @@ -9,3 +9,4 @@ swap: '(? The Docker Dashboard does not remove volumes when you delete the app stack. {: .warning} +For both of the following callouts, consult [the Docker release lifecycle](/release-lifecycle) for more information on when to use them. + > **Beta feature** > > The Builds view is currently in Beta. This feature may change or be removed from future releases. diff --git a/contribute/components/cards.md b/contribute/components/cards.md index 464f846667..c381815961 100644 --- a/contribute/components/cards.md +++ b/contribute/components/cards.md @@ -6,7 +6,7 @@ toc_max: 3 ## Example In a Bootstrap row, your columns need to add up to 12. Here are three cards in -a row, each of which takes up 1/3 (4/12) of the row. +a row, each of which takes up to 1/3 (4/12) of the row.
This takes up 1/3 of the row unless the screen is small, diff --git a/contribute/components/code-blocks.md b/contribute/components/code-blocks.md index 71d6ed3051..4e11344723 100644 --- a/contribute/components/code-blocks.md +++ b/contribute/components/code-blocks.md @@ -29,14 +29,14 @@ $ some other command ## Bash -Use the `bash` language code block when you want to a Bash script: +Use the `bash` language code block when you want to show a Bash script: ```bash #!/usr/bin/bash echo "deb https://packages.docker.com/1.12/apt/repo ubuntu-trusty main" | sudo tee /etc/apt/sources.list.d/docker.list ``` -If you want to illustrate an interactive shell, use `console` instead. +If you want to show an interactive shell, use `console` instead. In cases where you use `console`, make sure to add a dollar character for the user sign: diff --git a/contribute/components/images.md b/contribute/components/images.md index 21df3abc89..17bedbf4ae 100644 --- a/contribute/components/images.md +++ b/contribute/components/images.md @@ -8,7 +8,7 @@ toc_max: 3 - A small image: ![a small image](/assets/images/footer_moby_icon.png) -- A small image that is a link. The extra newline here makes it not show inline: +- A small image that's a link. The extra newline here makes it not show inline: [![a small image](/assets/images/footer_moby_icon.png)](https://www.docker.com/) @@ -25,7 +25,7 @@ toc_max: 3 ```html - A small image: ![a small cute image](/assets/images/footer_moby_icon.png) -- A small image that is a link. The extra newline here makes it not show inline: +- A small image that's a link. The extra newline here makes it not show inline: [![a small cute image](/assets/images/footer_moby_icon.png)](https://www.docker.com/) diff --git a/contribute/components/links.md b/contribute/components/links.md index 3f85c5ebfb..98c0c4a4a8 100644 --- a/contribute/components/links.md +++ b/contribute/components/links.md @@ -3,18 +3,43 @@ description: components and formatting examples used in Docker's docs title: Links toc_max: 3 --- -## Examples -It is best practice if [a link opens in a new window](https://docker.com/){: target="_blank" rel="noopener" class="_" } +## Internal links -#### Links to auto-generated content +Internal links should open [in the same window](/) + +Use the path to the final permalink for the file, without the `.md` extension and a `/` at the end. For example, [to link to this file](/contribute/components/links), use `[](/contribute/components/links)`. + +You can also have [a markdown link to a sub-heading or custom target ID](#external-links) + +### HTML + +```html +Internal links should open [in the same window](/) + +Use the path to the final permalink for the file, without the `.md` extension and a `/` at the end. For example, [to link to this file](/contribute/components/links), use `[](/contribute/components/links)`. + +You can also have [a markdown link to a sub-heading or custom target ID](#external-links) +``` + +## External links + +External links should open [in a new window](https://docker.com/){: target="_blank" rel="noopener" class="_" }, have a `/` at the end of the URL. + +### HTML + +```html +External links should open [in a new window](https://docker.com/){: target="_blank" rel="noopener" class="_" } +``` + +### Links to auto-generated content An example of a link to an auto-generated reference page that we pull in during docs builds: [/engine/reference/builder/#env](/engine/reference/builder/#env). - If you can't find a reference page in the GitHub repository, but see it out on `docs.docker.com`, you can surmise that it's probably auto-generated - from the codebase. (FYI, to view the Markdown source for the file, just click + from the codebase. (FYI, to view the Markdown source for the file, just select **Edit this page** on `docs.docker.com`. But don't use that URL in your docs.) - Go to the file in a web browser, grab everything after the domain name @@ -28,12 +53,6 @@ An example of a link to an auto-generated reference page that we pull in during ## HTML ```html - -It is best practice if [a link opens in a new window](https://docker.com/){: target="_blank" rel="noopener" class="_" } - -You can also have [a markdown link to a custom target ID](#formatting-examples) - An example of a link to an auto-generated reference page that we pull in during docs builds: [/engine/reference/builder/#env](/engine/reference/builder/#env). - ``` \ No newline at end of file diff --git a/contribute/components/tooltips.md b/contribute/components/tooltips.md index d1a7aecfb4..b7a43ac5a6 100644 --- a/contribute/components/tooltips.md +++ b/contribute/components/tooltips.md @@ -3,7 +3,7 @@ description: components and formatting examples used in Docker's docs title: Tooltips toc_max: 3 --- -Tooltips are not visible on mobile devices or touchscreens, so don't rely on them as the +Tooltips aren't visible on mobile devices or touchscreens, so don't rely on them as the only way to communicate important info. ## Examples diff --git a/contribute/components/videos.md b/contribute/components/videos.md index 3628869b47..c4d9c6dc0d 100644 --- a/contribute/components/videos.md +++ b/contribute/components/videos.md @@ -4,7 +4,7 @@ title: Videos toc_max: 3 --- -To embed a YouTube video on a docs page, open the video on YouTube, click +To embed a YouTube video on a docs page, open the video on YouTube, select **Share** > **Embed** and then copy the code displayed. For example, the video embedded on the Get Started page has the following code: diff --git a/contribute/contribute-guide.md b/contribute/contribute-guide.md index 3f3f7cd941..95a3bf5b7c 100644 --- a/contribute/contribute-guide.md +++ b/contribute/contribute-guide.md @@ -13,15 +13,15 @@ The live docs are published from the `main` branch. Therefore, you must create p There are two ways to contribute a pull request to the docs repository: -1. You can click **Edit this page** option in the right column of every page on [https://docs.docker.com/](/). +1. You can select the **Edit this page** option in the right column of every page on [https://docs.docker.com/](/). This opens the GitHub editor, which means you don't need to know a lot about Git, or even about Markdown. When you save, Git prompts you to create a fork if you don't already have one, and to create a branch in your fork and submit the pull request. 2. Fork the [docs GitHub repository]({{ site.repo }}). Suggest changes or add new content on your local branch, and submit a pull request (PR) to the `main` branch. - This is the manual, more advanced version of clicking 'Edit this page' on a published docs page. Initiating a docs changes in a PR from your own branch gives you more flexibility, as you can submit changes to multiple pages or files under a single pull request, and even create new topics. + This is the manual, more advanced version of selecting 'Edit this page' on a published docs page. Initiating a docs change in a PR from your own branch gives you more flexibility, as you can submit changes to multiple pages or files under a single pull request, and even create new topics. - For a demo of the components, tags, Markdown syntax, styles, etc. we use at [https://docs.docker.com/](/), see the Useful components section. + For a demo of the components, tags, Markdown syntax, styles, etc. used in [https://docs.docker.com/](/), see the components section. ## Important files @@ -41,17 +41,17 @@ Some files and directories are maintained in the upstream repositories. You can Help us review your PRs more quickly by following these guidelines. - Try not to touch a large number of files in a single PR if possible. -- Don't change whitespace or line wrapping in parts of a file you are not editing for other reasons. Make sure your text editor is not configured to +- Don't change whitespace or line wrapping in parts of a file you aren't editing for other reasons. Make sure your text editor isn't configured to automatically reformat the whole file when saving. - We highly recommend that you [build](#build-and-preview-the-docs-locally) and [test](#test-the-docs-locally) the docs locally before submitting a PR. -- A Netlify test runs for each PR that is against the `main` branch, and deploys the result of your PR to a staging site. The URL will be available at in the **Conversation** tab. Check the staging site to verify how your changes look and fix issues, if necessary. +- A Netlify test runs for each PR that is against the `main` branch, and deploys the result of your PR to a staging site. The URL will be available in the **Conversation** tab. Check the staging site to verify how your changes look and fix issues, if necessary. ### Collaborate on a pull request Unless the PR author specifically disables it, you can push commits into another contributor's PR. You can do it from the command line by adding and fetching their remote, checking out their branch, and adding commits to it. Even easier, -you can add commits from the Github web UI, by clicking the pencil icon for a +you can add commits from the GitHub web UI, by clicking the pencil icon for a given file in the **Files** view. If a PR consists of multiple small addendum commits on top of a more significant @@ -131,10 +131,11 @@ your editor to get real-time feedback on your writing. To get started, follow the [vale installation instructions](https://vale.sh/docs/vale-cli/installation/) for your operating system. To enable the vale integration for your editor, install the relevant plugin: -- [VS Code](https://github.com/errata-ai/vale-vscode) +- [VS Code](https://github.com/chrischinchilla/vale-vscode) - [Neovim](https://github.com/jose-elias-alvarez/null-ls.nvim/blob/main/doc/BUILTINS.md#vale) - [Emacs](https://github.com/tpeacock19/flymake-vale) - [Jetbrains](https://vale.sh/docs/integrations/jetbrains/) +- [Sublime Text](https://github.com/errata-ai/LSP-vale-ls) The vale rules that implement the Docker style guide are included in the Docker docs repository, in the `.github/vale` directory. Vale will automatically apply these rules when invoked in this diff --git a/contribute/file-conventions.md b/contribute/file-conventions.md index 5e8cb36fb7..5230b4c588 100644 --- a/contribute/file-conventions.md +++ b/contribute/file-conventions.md @@ -10,12 +10,12 @@ When you create a new .md file for new content, make sure: - File names are as short as possible - Try to keep the file name to one word or two words - Use a dash to separate words. For example: - - `add-seats.md` and `remove-seats.md`. - - `multiplatform-images` preferred to `multi-platform-images`. + - `add-seats.md` and `remove-seats.md`. + - `multiplatform-images` preferred to `multi-platform-images`. -## Frontmatter +## Front matter -The front-matter of a given page is in a section at the top of the Markdown +The front matter of a given page is in a section at the top of the Markdown file that starts and ends with three hyphens. It includes YAML content. The following keys are supported. The title, description, and keywords are required. @@ -33,7 +33,7 @@ following keys are supported. The title, description, and keywords are required. | sitemap | no | Exclude the page from indexing by search engines. When set to `false`, the page is excluded from `sitemap.xml`, and a `` header is added to the page. | Here's an example of a valid (but contrived) page metadata. The order of -the metadata elements in the front-matter isn't important. +the metadata elements in the front matter isn't important. ```liquid --- @@ -57,7 +57,7 @@ toc_max: 4 ## Body -The body of the page (with the exception of keywords) starts after the frontmatter +The body of the page (with the exception of keywords) starts after the front matter ### Text length diff --git a/contribute/style/formatting.md b/contribute/style/formatting.md index 6b580d096a..662bd386ee 100644 --- a/contribute/style/formatting.md +++ b/contribute/style/formatting.md @@ -7,41 +7,40 @@ toc_max: 2 ## Headings and subheadings -Readers pay fractionally more attention to headings, bulleted lists and links, so it's important to ensure the first two to three words in those items "front load" information as much as possible. +Readers pay fractionally more attention to headings, bulleted lists, and links, so it's important to ensure the first two to three words in those items "front load" information as much as possible. ### Best practice: - Headings and subheadings should let the reader know what they will find on the page. - They should describe succinctly and accurately what the content is about. - Headings should be short (no more than eight words), to the point and written in plain, active language. -- You should avoid puns, teasers and cultural references. +- You should avoid puns, teasers, and cultural references. - Skip leading articles (a, the, etc.) ## Page title -Page titles should be action orientated. For example: - - _Enable SCIM_ - - _Install Docker Desktop_ +Page titles should be action orientated. For example: - _Enable SCIM_ - _Install Docker Desktop_ ### Best practice: -- Make sure the title of your page and the TOC entry matches. -- If you want to use a ‘:’ in a page title in the table of contents (_toc.yaml), you must wrap the entire title in “” to avoid breaking the build. +- Make sure the title of your page and the table of contents (TOC) entry matches. +- If you want to use a ‘:’ in a page title in the table of contents (\_toc.yaml), you must wrap the entire title in “” to avoid breaking the build. - If you add a new entry to the TOC file, make sure it ends in a trailing slash (/). If you don't, the page won't show the side navigation. ## Images -Images, including screenshots, can help a reader better understand a concept. However, they should be used sparingly as they tend to go out-of-date quickly. +Images, including screenshots, can help a reader better understand a concept. However, you should use them sparingly as they tend to go out-of-date. ### Best practice: + - When you take screenshots: - - Don’t use lorem ipsum text. Try to replicate how the feature would be used in a real-world scenario, and use realistic text. - - Capture only the relevant UI. Don’t include unnecessary white space or areas of the UI that don’t help illustrate the point. - - Keep it small. If you don’t need to show the full width of the screen, don’t. - - Review how the image renders on the page. Make sure the image isn’t blurry or overwhelming. - - Be consistent. Coordinate screenshots with the other screenshots already on a documentation page for a consistent reading experience. - - To keep the Git repository light, compress the images (losslessly). Be sure to compress the images before adding them to the repository. Compressing images after adding them to the repository actually worsens the impact on the Git repo (however, it still optimizes the bandwidth during browsing). - - Don't forget to remove images from the repo that are no longer used. + - Don’t use lorem ipsum text. Try to replicate how someone would use the feature in a real-world scenario, and use realistic text. + - Capture only the relevant UI. Don’t include unnecessary white space or areas of the UI that don’t help illustrate the point. + - Keep it small. If you don’t need to show the full width of the screen, don’t. + - Review how the image renders on the page. Make sure the image isn’t blurry or overwhelming. + - Be consistent. Coordinate screenshots with the other screenshots already on a documentation page for a consistent reading experience. + - To keep the Git repository light, compress the images (losslessly). Be sure to compress the images before adding them to the repository. Compressing images after adding them to the repository actually worsens the impact on the Git repository (however, it still optimizes the bandwidth during browsing). + - Don't forget to remove images from the repository that are no longer used. For information on how to add images to your content, see [Useful component and formatting examples](../components/images.md). @@ -55,20 +54,19 @@ The best links offer readers another way to scan information. ### Best practice: -- Use plain language that does not mislead or promise too much. +- Use plain language that doesn't mislead or promise too much. - Be short and descriptive (around five words is best). -- Allow people to predict (with a fair degree of confidence) what they will get if they click. Mirror the heading text on the destination page in links whenever possible. +- Allow people to predict (with a fair degree of confidence) what they will get if they select a link. Mirror the heading text on the destination page in links whenever possible. - Front-load user-and-action-oriented terms at the beginning of the link (Download our app). - Avoid generic calls to action (such as click here, find out more). -- Do not include any end punctuation when you hyperlink text (for example, periods, question marks, or exclamation points). -- Do not make link text italics or bold, unless it would be so as normal body copy. -- Make sure your link opens in a new tab so it doesn't interrupt the user-flow. +- Don't include any end punctuation when you hyperlink text (for example, periods, question marks, or exclamation points). +- Don't make link text italics or bold, unless it would be so as normal body copy. For information on how to add links to your content, see [Useful component and formatting examples](../components/links.md). ## Code and code samples -Format the following as code: docker commands, instructions, and filenames (package names). +Format the following as code: Docker commands, instructions, and filenames (package names). To apply inline code style, wrap the text in a single backtick (`). @@ -85,49 +83,49 @@ For information on how to add code blocks to your content, see [Useful component - Commands that users will copy and run: - Add a single command per code block if a command produces output or requires the user to verify the results. - Add command output to a separate code block from the command. -- Commands that users will not copy and run: +- Commands that users won't copy and run: - Use POSIX-compatible syntax. It's not necessary to include Windows syntax. - Wrap optional arguments in square brackets ( [ ] ). - - Use pipes ( \| ) between mutually exclusive arguments. + - Use pipes ( \| ) between mutually exclusive arguments. - Use three dots ( ... ) after repeated arguments. ### Best practice for code: - - Indent code blocks by 3 spaces when you nest a code block under a list item. - - Use three dots ( ... ) when you omit code. +- Indent code blocks by 3 spaces when you nest a code block under a list item. +- Use three dots ( ... ) when you omit code. ## Callouts -Use callouts to emphasize selected information in a page. +Use callouts to emphasize selected information on a page. ### Best practice: -- Format the word Warning, Important, or Note in bold. Do not bold the content within the callout. +- Format the word Warning, Important, or Note in bold. Don't bold the content within the callout. - It's good practice to avoid placing a lot of text callouts on one page. They can create a cluttered appearance if used to excess, and you'll diminish their impact. -| Text callout | Use case scenario | Color or callout box | -| --- | --- | --- | -| Warning | Use a Warning tag to signal to the reader where actions may cause damage to hardware or software loss of data. | Red | -| | ✅ Example: Warning: When you use the docker login command, your credentials are stored in your home directory in .docker/config.json. The password is base64-encoded in this file. | | -| Important | Use an Important tag to signal to the reader where actions may cause issues of a lower magnitude. | Yellow | -| | ✅ Example: Update to the Docker Desktop terms | | -| Note | Use the Note tag for information that may not apply to all readers, or if the information is tangential to a topic. | Blue | -| | ✅ Example: Deleting a repository deletes all the images it contains and its build settings. This action cannot be undone.| +| Text callout | Use case scenario | Color or callout box | +| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | +| Warning | Use a Warning tag to signal to the reader where actions may cause damage to hardware or software loss of data. | Red | +| | ✅ Example: Warning: When you use the docker login command, your credentials are stored in your home directory in .docker/config.json. The password is base64-encoded in this file. | | +| Important | Use an Important tag to signal to the reader where actions may cause issues of a lower magnitude. | Yellow | +| | ✅ Example: Update to the Docker Desktop terms | | +| Note | Use the Note tag for information that may not apply to all readers, or if the information is tangential to a topic. | Blue | +| | ✅ Example: Deleting a repository deletes all the images it contains and its build settings. This action cannot be undone. | -For information on how to add call outs to your content, see [Useful component and formatting examples](../components/call-outs.md). +For information on how to add callouts to your content, see [Useful component and formatting examples](../components/call-outs.md). ## Navigation When documenting how to navigate through the Docker Desktop or Docker Hub UI: - Always use location, then action. For example: - _From the **Visibility** dropdown list (location), select Public (action)._ + _From the **Visibility** drop-down list (location), select Public (action)._ - Be brief and specific. For example: - Do: _Select **Save**._ - Do not: _Select **Save** for the changes to take effect._ + Do: _Select **Save**._ + Don't: _Select **Save** for the changes to take effect._ - If a step must include a reason, start the step with it. This helps the user scan more quickly. - Do: _To view the changes, in the merge request, select the link._ - Do not: _Select the link in the merge request to view the changes_ + Do: _To view the changes, in the merge request, select the link._ + Don't: _Select the link in the merge request to view the changes_ ## Optional steps @@ -147,23 +145,32 @@ In these cases, use < and > to call out where a reader must replace text with th ## Tables -Tables should be used to describe complex information in a straightforward manner. +Use tables to describe complex information in a straightforward manner. -Note that in many cases, an unordered list is sufficient to describe a list of items with a single, simple description per item. But, if you have data that’s best described by a matrix, tables are the best choice. +Note that in many cases, an unordered list is enough to describe a list of items with a single, simple description per item. But, if you have data that’s best described by a matrix, tables are the best choice. ### Best practice: - Use sentence case for table headings. -- To keep tables accessible and scannable, tables should not have any empty cells. If there is no otherwise meaningful value for a cell, consider entering N/A for ‘not applicable’ or None. +- To keep tables accessible and scannable, tables shouldn't have any empty cells. If there is no otherwise meaningful value for a cell, consider entering N/A for ‘not applicable’ or None. For information on how to add tables to your content, see [Useful component and formatting examples](../components/tables.md). ## Referring to file types -When you're discussing a file type, use the formal name of the type. Do not use the filename extension to refer generically to the file type. +When you're discussing a file type, use the formal name of the type. Don't use the filename extension to refer generically to the file type. | Correct | Incorrect | | --- | --- | | a PNG file | a .png file | | a Bash file | an .sh file | +## Referring to units + +When you're referring to units of measurement, use the abbreviated form in all caps, with a space between the value and the unit. For example: + + | Correct | Incorrect | + | --- | --- | + | 10 GB | 10GB | + | 10 GB | 10 gb | + | 10 GB | 10 gigabytes | \ No newline at end of file diff --git a/contribute/style/grammar.md b/contribute/style/grammar.md index 4d64759d89..0bca40c0b7 100644 --- a/contribute/style/grammar.md +++ b/contribute/style/grammar.md @@ -17,14 +17,14 @@ An initialism is a type of acronym that comprises a group of initial letters use - Spell out lesser-known acronyms or initialisms on first use, then follow with the acronym or initialism in parentheses. After this, throughout the rest of your page or document, use the acronym or initialism alone. > ‘You can use single sign-on (SSO) to sign in to Notion. You may need to ask your administrator to enable SSO.’ -- Where the acronym or initialism is more commonly used than the full phrase, for example, URL, HTML, you do not need to follow this spell-it-out rule. +- Where the acronym or initialism is more commonly used than the full phrase, for example, URL, HTML, you don't need to follow this spell-it-out rule. - Use all caps for acronyms of file types (a JPEG file). - Don't use apostrophes for plural acronyms. ✅URLs ❌URL’S - Avoid using an acronym for the first time in a title or heading. If the first use of the acronym is in a title or heading, introduce the acronym (in parentheses, following the spelled-out term) in the first body text that follows. ## Bold and italics -Unless you're referring to UI text or user-defined text, you should not add emphasis to text. Clear, front-loaded wording makes the subject of a sentence clear. +Unless you're referring to UI text or user-defined text, you shouldn't add emphasis to text. Clear, front-loaded wording makes the subject of a sentence clear. ### Best practice: @@ -45,15 +45,15 @@ The following content elements should use sentence case: - Column and row headers in tables - Links - Sentences (of course) -- Anything in the Ul including navigation labels, buttons, headings +- Anything in the UI including navigation labels, buttons, headings ### Best practice - As a general rule, it's best to avoid the use of ALL CAPITALS in most content types. They are more difficult to scan and take up more space. While all caps can convey emphasis, they can also give the impression of shouting. - If a company name is all lowercase or all uppercase letters, follow their style, even at the beginning of sentences: DISH and bluecrux. When in doubt, check the company's website. -- Use title case for Docker solutions : Docker Extensions, Docker Hub. +- Use title case for Docker solutions: Docker Extensions, Docker Hub. - Capitalize a job title if it immediately precedes a name (Chief Executive Officer Scott Johnston). -- Do not capitalize a job title that follows a name or is a generic reference (Scott Johnston, chief executive officer of Docker). +- Don't capitalize a job title that follows a name or is a generic reference (Scott Johnston, chief executive officer of Docker). - Capitalize department names when you refer to the name of a department, but use lower case if you are talking about the field of work and not the actual department. - When referring to specific user interface text, like a button label or menu item, use the same capitalization that’s displayed in the user interface. @@ -65,7 +65,7 @@ Following our conversational approach, it's acceptable to use contractions in al ### Best practice: -- Stay consistent - don't switch between contractions and their spelled-out equivalents in body copy or Ul text. +- Stay consistent - don't switch between contractions and their spelled-out equivalents in body copy or UI text. - Avoid negative contractions (can't, don't, wouldn't, and shouldn't) whenever possible. Try to rewrite your sentence to align with our helpful approach that puts the focus on solutions, not problems. - Never contract a noun with is, does, has, or was as this can make it look like the noun is possessive. Your container is ready. Your container’s ready. @@ -82,9 +82,7 @@ In all UI content and technical documentation, use decimals instead of fractions ### Best practice: - Always carry decimals to at least the hundredth place (33.76). - - In tables, align decimals on the decimal point. - - Add a zero before the decimal point for decimal fractions less than one (0.5 cm). ## Lists @@ -97,7 +95,7 @@ Lists are a great way to break down complex ideas and make them easier to read a - Don’t add commas (,) or semicolons (;) to the ends of list items. - Some content types may use bulleted lists that contain 10 items, but it's preferable to break longer lists into several lists, each with its own subheading or introduction. - Never create a bulleted list with only one bullet, and never use a dash to indicate a bulleted list. -- If your list items are fragments, capitalize the list items for ease of scanning but do not use terminal punctuation. +- If your list items are fragments, capitalize the list items for ease of scanning but don't use terminal punctuation. Example: I went to the shops to buy: @@ -107,13 +105,12 @@ Example: - Eggs - Make sure all your list items are parallel. This means you should structure each list item in the same way. They should all be fragments, or they should all be complete sentences. If you start one list item with a verb, then start every list item with a verb. - Every item in your list should start with a capital letter unless they’re parameters or commands. -- Nested sequential lists are labelled with lowercase letters. For example: +- Nested sequential lists are labeled with lowercase letters. For example: 1. Top level 2. Top level 1. Child step 2. Child step - ## Numbers When you work with numbers in content, the best practices include: @@ -123,7 +120,7 @@ When you work with numbers in content, the best practices include: - Recast a sentence, rather than begin it with a number (unless it's a year). - When you cite numbers in an example, write them out as they appear in any accompanying screenshots. - Write numbers out as they appear on the platform when you cite them in an example. -- To refer to large numbers in abstract (such as thousands, millions, and billions), use a combination of words and numbers. Do not abbreviate numeric signifiers. +- To refer to large numbers in abstract (such as thousands, millions, and billions), use a combination of words and numbers. Don't abbreviate numeric signifiers. - Avoid using commas in numbers because they can represent decimals in different cultures. For numbers that are five digits or more, use a space to separate. @@ -135,7 +132,7 @@ When you work with numbers in content, the best practices include: ### Versions -When writing version numbers for release notes, follow the example below: +When writing version numbers for release notes, use the following example: - version 4.8.2 - v1.0 @@ -146,7 +143,7 @@ When writing version numbers for release notes, follow the example below: ### Colons and semicolons - Use colons to: introduce a list inline in a sentence; introduce a bulleted or numbered list; and provide an explanation. -- Do not use semicolons. Use two sentences instead. +- Don't use semicolons. Use two sentences instead. ### Commas @@ -167,9 +164,9 @@ Avoid the use of exclamation marks. ### Parentheses -Don't use parentheses in technical documentation. They can reduce the readability of a sentence. +Don't use parentheses in technical documentation. They can reduce the readability of a sentence. ## Third party documentation -If you are documenting a task that requires the use of a third-party product, link out to the third-party's documentation. Do not copy the content because it might violate copyright. It can also result in an unnecessary maintenance burden of having to keep the docs up-to-date when the third-party changes or updates their product. It is best practice to link to the single source of truth. +If you are documenting a task that requires the use of a third-party product, link out to the third-party's documentation. Don't copy the content because it might violate copyright. It can also result in an unnecessary maintenance burden of having to keep the docs up-to-date when the third-party changes or updates their product. It is best practice to link to the single source of truth. diff --git a/contribute/style/recommended-words.md b/contribute/style/recommended-words.md index 543a1c7630..6c1c75e025 100644 --- a/contribute/style/recommended-words.md +++ b/contribute/style/recommended-words.md @@ -4,35 +4,39 @@ description: Recommended word list for Technical documentation keywords: recommended word list, style guide, contribute --- -To help ensure consistency across our documentation, the Technical Writing team recommends these wording choices. +To help ensure consistency across documentation, the Technical Writing team recommends these wording choices. #### & (ampersand) + Don't use `&` instead of `and` in headings, text, navigation, UI copy, or tables of contents. #### above -Try to avoid using `above` when referring to an example or table in a documentation page. If required, use `previous` instead. + +Try to avoid using `above` when referring to an example or table in a documentation page. If required, use `previous` instead. For example: _In the previous example, the dog had fleas._ #### account name + Don't use. Instead, use `username`. #### admin + Write out `administrator` on first use. Use `admin` if it's the name of a UI label or other element. #### allows -Don't use. Instead use `lets`. +Don't use. Instead, use `lets``. #### as of this writing -Avoid because this phrase is implied. The phrase can also prematurely disclose product or feature strategy or inappropriately imply that a product or feature might change. - +Avoid because the writing itself implies this phrase. The phrase can also prematurely share product or feature strategy or inappropriately imply that a product or feature might change. #### below -Try to avoid `below` when referring to an example or table in a documentation page. If required, use `following` instead. + +Try to avoid `below` when referring to an example or table on a documentation page. If required, use `following` instead. For example: @@ -40,30 +44,32 @@ _In the following example, the dog had fleas._ #### checkbox -Use one word for `checkbox`. Do not use `check box`. +Use one word for `checkbox`. Don't use `check box`. You select (not check or enable) and clear (not deselect or disable) checkboxes. #### click -Do not use `click`. Instead, use `select` with buttons, links, menu items, and lists.  +Don't use `click`. Instead, use `select` with buttons, links, menu items, and lists. Select applies to more devices, while click is more specific to a mouse. -#### currently +#### currently -Do not use `currently` when talking about the product or its features. The documentation describes the product as it is today. +Don't use `currently` when talking about the product or its features. The documentation describes the product as it is today. -#### deselect +#### deselect -Don’t use `deselect`. Instead, use `clear`. +Don’t use `deselect`. Instead, use `clear`. #### disable -Do not use `disable`. Implies that disability is a less-desired or negative state. +Don't use `disable`. Implies that disability is a less-desired or negative state. Instead, use `turn off` or `toggle off`. +There are times with more technical features when the development team uses `disable`, and in these cases, it's OK to use the term. + #### earlier Use `earlier` when talking about version numbers. @@ -77,25 +83,27 @@ Instead of: _In Docker Desktop 4.1 and lower._ #### easy, easily + What might be easy for you might not be easy for others. Try eliminating this word from the sentence because usually the same meaning can be conveyed without it. #### e.g. + Don't use. Instead, use phrases like `for example` or `such as`. #### enable -Do not use `enable`. Implies that disability is a less-desired or negative state. +Don't use `enable`. Implies that disability is a less-desired or negative state. Instead, use `turn on` or `toggle on`. +There are times with more technical features when the development team uses `enable`, and in these cases, it's OK to use the term. + #### execute Avoid where possible. Use `run` instead. -#### K8s -Do not use. Use `Kubernetes` instead. - #### later + Use `later` when talking about version numbers. Use: @@ -111,12 +119,15 @@ _In Docker Desktop 4.1 and higher…_ or _In Docker Desktop 4.1 and above…_ Don't use `please` in the normal course of explaining how to use a product, even if you're explaining a difficult task. Also don't use the phrase `please note`. #### register + Use `register` instead of sign up when talking about creating an account. #### repo + Don't use. Instead, use `repository`. #### respectively + Avoid `respectively` and be more precise instead. #### scroll @@ -124,14 +135,21 @@ Avoid `respectively` and be more precise instead. Avoid. Use a verb phrase such as _move through_ or _navigate to_ instead, if the context is clear. #### sign in -Use `sign in` instead of `sign on` or `log on` or `log in`. If the user interface has different words, use those. -Also use `sign in to` instead of `sign into`. +Use `sign in` instead of `sign on`, `signon`, `log on`, `logon`, or `log in`, `login`. If the user interface uses different words, use those. +Use `sign in to` instead of `sign into`. #### sign up + Use `register` or `create account` instead of `sign up` when talking about creating an account. +#### tab versus view + +Use `view` when referring to a major section in a UI. Use `tab` when referring to a sub-section in the UI. + +For example, in Docker Desktop, the **Images** view and the **Local** tab. + #### toggle You turn on or turn off a toggle. For example: @@ -139,15 +157,16 @@ You turn on or turn off a toggle. For example: _Turn on the dark mode toggle._ #### upgrade -Use `upgrade` for when describing a higher subscription tier + +Use `upgrade` when describing a higher subscription tier #### vs. -Don't use `vs.` as an abbreviation for versus; instead, use the unabbreviated `versus`. +Don't use `vs.` as an abbreviation for versus; instead, use the unabbreviated `versus`. #### we -Try to avoid `we` and focus instead on how the user can accomplish something in Docker. +Try to avoid `we` and focus instead on how the user can carry out something in Docker. Use: diff --git a/contribute/style/terminology.md b/contribute/style/terminology.md index fd2fe4f218..826f11ad7e 100644 --- a/contribute/style/terminology.md +++ b/contribute/style/terminology.md @@ -6,19 +6,19 @@ keywords: terminology, style guide, contribute #### `compose.yaml` -The current designation for the Compose file, as it is a file, format as code. +The current designation for the Compose file, as it's a file, format as code. #### Compose plugin -The compose app as an add-on (for Docker CLI) that can be enabled/disabled. +The compose plugin as an add-on (for Docker CLI) that can be enabled/disabled. #### Digest -The long number that’s automatically created every time you push an image. You can pull an image by Digest or by Tag. +A long string that’s automatically created every time you push an image. You can pull an image by Digest or by Tag. #### Docker Compose -Use when we talk about the application, or all the functionality associated with the application. +Use when we talk about the application, or all the functionality associated with the application. #### `docker compose` @@ -28,9 +28,13 @@ Use code formatting for referring to the commands in text and command usage exam Use when referring to family of Compose commands as offered from the Docker CLI. +#### K8s + +Don't use. Use `Kubernetes` instead. + #### Multi-platform -(broad meaning) Mac vs Linux vs Microsoft but also pair of platform architecture such as in Linux/amd64 and Linux/arm64; (narrow meaning) windows/linux/mac. +(broad meaning) Mac vs Linux vs Microsoft but also pair of platform architecture such as in Linux/amd64 and Linux/arm64; (narrow meaning) Windows/Linux/macOS. #### Multi-architecture / multi-arch @@ -48,7 +52,7 @@ Organization or User name. Every image needs a namespace to live under. A node is a physical or virtual machine running an instance of the Docker Engine in swarm mode. Manager nodes perform swarm management and orchestration duties. By default manager nodes are also worker nodes. -Worker nodes execute tasks. +Worker nodes invoke tasks. #### Registry diff --git a/contribute/style/voice-tone.md b/contribute/style/voice-tone.md index ddccbfffb2..9e244550e0 100644 --- a/contribute/style/voice-tone.md +++ b/contribute/style/voice-tone.md @@ -4,7 +4,7 @@ description: Docker's voice and tone keywords: style guide, voice, tone, content standards --- -# Voice +## Voice At Docker, we've been the customer. We're developers developing for developers. We speak with experience and knowledge and without arrogance or ego. We want to inform and empower people without being confusing or pushy. @@ -26,19 +26,19 @@ All of this means that when we write documentation and UI copy: 3. **We are relaxed.** Our demeanor is casual but not lazy, smart but not arrogant, and focused but not cold. Our voice should be welcoming and warm. 4. **We are inclusive.** Developers are developers no matter how much code they've written. Every person is as much a part of our community as the next. We are accepting of all developers from all industries and experience levels. -# Tone +## Tone Docker's tone is usually informal, but we believe it's always more important to be clear over comical. We're relaxed, but we're not inappropriate or unprofessional. -## Friendly tone +### Friendly tone -Use a tone that's natural, friendly, and respectful without being overly colloquial or full of jargons. Write to inform and empower developers without being confusing or pushy. It’s OK to use contractions as long as the sentence doesn’t become too slangy or informal. +Use a tone that's natural, friendly, and respectful without being overly colloquial or full of jargon. Write to inform and empower developers without being confusing or pushy. It’s OK to use contractions as long as the sentence doesn’t become too slangy or informal. -**Avoid overdoing the politeness.** It is good to be friendly and polite, but using ‘please’ in technical documentation or UI copy might be overdoing the politeness. +**Avoid overdoing politeness.** It is good to be friendly and polite, but using ‘please’ in technical documentation or UI copy might be overdoing the politeness. -## Positive language +### Positive language -Use a positive language. Instead of highlighting the limitations and what the users cannot do, emphasize on the positive outcomes. +Use positive language. Instead of highlighting the limitations and what the users cannot do, emphasize the positive outcomes. For example, **instead of**: