From 642554a7922e4876a0bf51170ffd8a3325a640c1 Mon Sep 17 00:00:00 2001 From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> Date: Wed, 10 Aug 2022 09:30:49 +0100 Subject: [PATCH 01/14] SG test. --- _data/toc.yaml | 29 ++++- components.md | 2 +- contribute/checklist.md | 40 +++++++ contribute/contribute-guide.md | 128 +++++++++++++++++++++ contribute/file-conventions.md | 93 +++++++++++++++ contribute/overview.md | 69 +++++++++++ contribute/style/formatting.md | 158 +++++++++++++++++++++++++ contribute/style/grammar.md | 159 ++++++++++++++++++++++++++ contribute/style/recommended-words.md | 110 ++++++++++++++++++ contribute/style/terminology.md | 60 ++++++++++ contribute/style/voice-tone.md | 53 +++++++++ contribute/template.md | 0 test.md | 2 +- 13 files changed, 899 insertions(+), 4 deletions(-) create mode 100644 contribute/checklist.md create mode 100644 contribute/contribute-guide.md create mode 100644 contribute/file-conventions.md create mode 100644 contribute/overview.md create mode 100644 contribute/style/formatting.md create mode 100644 contribute/style/grammar.md create mode 100644 contribute/style/recommended-words.md create mode 100644 contribute/style/terminology.md create mode 100644 contribute/style/voice-tone.md create mode 100644 contribute/template.md diff --git a/_data/toc.yaml b/_data/toc.yaml index 8d3181a4fcd3..d12586d4aa2e 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -15,6 +15,9 @@ horizontalnav: - title: Samples path: /samples/ node: samples +- title: Contribute + path: /contribute/overview/ + node: contribute # TODO unify navbbar links: homepage currently has a custom "articles" link hide_home: true @@ -1649,6 +1652,28 @@ manuals: title: Getting help - path: /release-notes/ title: Release notes - - path: /support/ - title: Get Support \ No newline at end of file + title: Get Support + +contribute: + - path: /contribute/overview/ + title: Contribute to Docker's docs + - path: /contribute/contribute-guide/ + - sectiontitle: Style guide + section: + - path: /contribute/style/grammar/ + title: Grammar and style + - path: /contribute/style/formatting/ + title: Formatting + - path: /contribute/style/recommended-words/ + title: Recommended word list + - path: /contribute/style/terminology/ + title: Docker terminology + - path: /contribute/style/voice-tone/ + title: Voice and tone + - path: /contribute/file-conventions/ + title: Source file conventions + - path: /components/ + title: Useful components + - path: /contribute/checklist + title: Writing checklist \ No newline at end of file diff --git a/components.md b/components.md index 048117c130f0..36147964582b 100644 --- a/components.md +++ b/components.md @@ -1,6 +1,6 @@ --- description: Components page -title: Components +title: Useful components sitemap: false --- diff --git a/contribute/checklist.md b/contribute/checklist.md new file mode 100644 index 000000000000..22a1aca951f3 --- /dev/null +++ b/contribute/checklist.md @@ -0,0 +1,40 @@ +--- +title: Writing checklist +description: A helpful writing checklist when creating documentation +keywords: checklist, documentation, style guide, contribute +--- + +Use this checklist to communicate in a way that is clear, helpful, and consistent with the rest of Docker Docs. + +##### Used active voice + +Active voice is specific and removes ambiguity. If you can add ‘by zombies’ after the verb, you’ll know you’re using passive voice. + +##### Written clear sentences that get to the point + +Write short, concise sentences. Punchy sentences are faster to read and easier to understand. + +##### Used subheadings and bulleted lists to break up the page + +This helps ‘scanners’ find the information they need quickly and easily. + +##### Started the title of your page with a verb + +For example, _Install Docker Desktop_. + +##### Checked that the left-hand table of content title in docs.docker.com, matches the title displayed on the page + +##### Checked for broken links and images + +Use relative links to link to other pages or images within the docker.github.io repo. + +##### Checked that any redirects you may have added, work + +For information on how to add redirects, see [Source file conventions](file-conventions.md) + +##### Used bold on any UI elements you refer to in your content + +##### Completed a final spelling, punctuation, and grammar check + +For more in-depth information on our Style Guide, explore the [Grammar](style/grammar.md) or [Formatting](style/grammar.md) guides. + diff --git a/contribute/contribute-guide.md b/contribute/contribute-guide.md new file mode 100644 index 000000000000..12ea8d9c21b2 --- /dev/null +++ b/contribute/contribute-guide.md @@ -0,0 +1,128 @@ +--- +title: Contributing guidelines +description: Guidelines for contributing to Docker's docs +keywords: contribute, guide, style guide +--- + +## Contribution guidelines + +The live docs are published from the `master` branch. Therefore, you must create pull requests against the `master` branch for all content updates. This includes: + +- Conceptual and task-based information +- Restructuring / rewriting +- Doc bug fixing +- Fixing typos, broken links, and any grammar errors + +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/](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](https://github.com/docker/docker.github.io). Suggest changes or add new content on your local branch, and submit a pull request (PR) to the `master` 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. + + For a demo of the components, tags, Markdown syntax, styles, etc we use at [https://docs.docker.com/](https://docs.docker.com/), see [test.md](/test.md). + +### Important files + +Here’s a list of some of the important files: + +- `/_data/toc.yaml` defines the left-hand navigation for the docs +- `/js/docs.js` defines most of the docs-specific JS such as the table of contents (ToC) generation and menu syncing +- `/css/style.scss` defines the docs-specific style rules +- `/_layouts/docs.html` is the HTML template file, which defines the header and footer, and includes all the JS/CSS that serves the docs content + +### Files not edited here + +Some files and directories are maintained in the upstream repositories. You can find a list of such files in [`_config_production.yml`](_config_production.yml#L52). Pull requests against these files will be rejected. + +## Pull request guidelines + +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 + automatically reformat the whole file when saving. +- We highly recommend that you build the docs locally and verify your changes before submitting a PR. See the section [Build and preview the docs locally](#build-and-preview-the-docs-locally). +- A Netlify test runs for each PR that is against the `master` 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. +- Use relative linking to link to other topics. See [Relative linking for GitHub viewing](#relative-linking-for-GitHub-viewing). + +## 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 +given file in the **Files** view. + +If a PR consists of multiple small addendum commits on top of a more significant +one, the commit will usually be "squash-merged", so that only one commit is +merged into the `master` branch. In some scenarios where a squash and merge isn't appropriate, all commits are kept separate when merging. + +## Per-PR staging on GitHub + +A Netlify test runs for each PR created against the `master` branch and deploys the result of your PR to a staging site. When the site builds successfully, you will see a comment in the **Conversation** tab in the PR stating **Deploy Preview for docsdocker ready!**. Click the **Browse the preview** URL and check the staging site to verify how your changes look and fix issues, if necessary. Reviewers also check the staged site before merging the PR to protect the integrity of the docs site. + +## Build and preview the docs locally + +On your local machine, clone the docs repository: + +```bash +git clone --recursive https://github.com/docker/docker.github.io.git +cd docker.github.io +``` + +Then, build and run the documentation using [Docker Compose](https://docs.docker.com/compose/) + +```bash +docker compose up -d --build +``` + +> You need Docker Compose to build and run the docs locally. Docker Compose is included with [Docker Desktop](https://docs.docker.com/desktop/). +> If you don't have Docker Desktop installed, follow the [instructions](https://docs.docker.com/compose/install/) to install Docker Compose. + +When the container is built and running, visit [http://localhost:4000](http://localhost:4000) in your web browser to view the docs. + +To rebuild the docs after you made changes, run the `docker compose up` command +again. This rebuilds the docs, and updates the container with your changes: + +```bash +docker compose up -d --build +``` + +To stop the staging container, use the `docker compose down` command: + +```bash +docker compose down +``` + +### Build the docs with deployment features enabled + +The default configuration for local builds of the documentation disables some +features to allow for a shorter build-time. The following options differ between +local builds, and builds that are deployed to [docs.docker.com](https://docs.docker.com/): + +- search auto-completion, and generation of `js/metadata.json` +- Google Analytics +- page ratings +- `sitemap.xml` generation +- minification of stylesheets (`css/style.css`) +- adjusting "edit this page" links for content in other repositories + +If you want to contribute in these areas, you can perform a "production" build +locally. To preview the documentation with deployment features enabled, set the `JEKYLL_ENV` environment variable when building the documentation: + +```bash +JEKYLL_ENV=production docker compose up --build +``` + +When the container is built and running, visit [http://localhost:4000](http://localhost:4000) in your web browser to view the docs. + +To rebuild the docs after you make changes, repeat the steps above. + +## Copyright and license + +Copyright 2013-2022 Docker, inc, released under the Apache 2.0 license. \ No newline at end of file diff --git a/contribute/file-conventions.md b/contribute/file-conventions.md new file mode 100644 index 000000000000..56ecc51d40bb --- /dev/null +++ b/contribute/file-conventions.md @@ -0,0 +1,93 @@ +--- +title: Source file conventions +description: How new .md files should be formatted +keywords: source file, contribute, style guide +--- + +## File name + +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` which you can find under /subscription. + - `multiplatform-images` preferred to `multi-platform-images`. + +## Frontmatter + +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. + +| Key | Required | Description | +|------------------------|-----------|-----------------------------------------| +| title | yes | The page title. This is added to the HTML output as a `

` level header. | +| description | yes | A sentence that describes the page contents. This is added to the HTML metadata. It’s not rendered on the page. | +| keywords | yes | A comma-separated list of keywords. These are added to the HTML metadata. | +| redirect_from | no | A YAML list of pages which should redirect to the current page. At build time, each page listed here is created as an HTML stub containing a 302 redirect to this page. | +| notoc | no | Either `true` or `false`. If `true`, no in-page TOC is generated for the HTML output of this page. Defaults to `false`. Appropriate for some landing pages that have no in-page headings.| +| toc_min | no | Ignored if `notoc` is set to `true`. The minimum heading level included in the in-page TOC. Defaults to `2`, to show `

` headings as the minimum. | +| toc_max | no | Ignored if `notoc` is set to `false`. The maximum heading level included in the in-page TOC. Defaults to `3`, to show `

` headings. Set to the same as `toc_min` to only show `toc_min` level of headings. | +| skip_read_time | no | Set to `true` to disable the 'Estimated reading time' banner for this page. | +| 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. + +```liquid +--- +description: Instructions for installing Docker Engine on Ubuntu +keywords: requirements, apt, installation, ubuntu, install, uninstall, upgrade, update +title: Install Docker Engine on Ubuntu +redirect_from: +- /ee/docker-ee/ubuntu/ +- /engine/installation/linux/docker-ce/ubuntu/ +- /engine/installation/linux/docker-ee/ubuntu/ +- /engine/installation/linux/ubuntu/ +- /engine/installation/linux/ubuntulinux/ +- /engine/installation/ubuntulinux/ +- /install/linux/docker-ce/ubuntu/ +- /install/linux/docker-ee/ubuntu/ +- /install/linux/ubuntu/ +- /installation/ubuntulinux/ +toc_max: 4 +--- +``` + +## Body + +The body of the page (with the exception of keywords) starts after the frontmatter + +### Paragraphs and new lines + +**To change the line without creating a paragraph:** + +Convention: + +✅ 2 trailing spaces (at the end of line). As in sample below where “[]” represents a whitespace character. + +```markdown +This is a sample sentence[][]. +Next sentence coming here. +``` + +❌Don’t use the HTML tag
+ +Context: + +We want to avoid mixing HTML with our markdown markup as much possible. There are some HTML tags that we use that provide some presentation enrichment like tabs, etc. but we prefer the markdown markup whenever it solves the ask in question. + +**Note** that simple trailing and isolated white spaces will probably be removed after linters are applied. + +**Paragraphs** + +CR:LF or pressing ENTER to create new lines + +**Indentation ?** + +- Empty lines and end of file +- Cross-references and upstream repos + +### Text length + +Splitting long lines (preferably up to 80 characters) can make it easier to provide feedback on small chunks of text. diff --git a/contribute/overview.md b/contribute/overview.md new file mode 100644 index 000000000000..dcf7930367f3 --- /dev/null +++ b/contribute/overview.md @@ -0,0 +1,69 @@ +--- +title: Contribute to Docker's docs +--- +We deeply value documentation contributions from the Docker community. We'd like to make it as easy +as possible for you to work in this repository. The following sections guide you through the process of contributing to Docker documentation. + +This section defines the standards for Docker documentation, including grammar, formatting, word use, and more. + +
+
+
+ +
Contribution guidelines
+

+ Learn about the process of contributing to our docs. +

+ +
+
+ +
Grammar guide
+

+ Explore Docker's grammar guide. +

+ +
+
+ +
Formatting guidelines
+

+ Learn how to format your content to match the rest of our documentation. + your applications. +

+ +
+
+ +
Recommended word list
+

+ This section can help you choose the right words for your content. +

+ +
+
+ +
Source file conventions
+

+ +

+ +
+
+ +
Docker terminology
+

+ +

+ +
+
+
+ +### Additional resources + +We also provide: + +- A page of [useful components](../components.md) you can add to your documentation. +- Information on Docker's [tone and voice](style/voice-tone.md). +- A [writing checklist](checklist.md) to help you when you're contributing to Docker's documenation. \ No newline at end of file diff --git a/contribute/style/formatting.md b/contribute/style/formatting.md new file mode 100644 index 000000000000..bb42380a23cb --- /dev/null +++ b/contribute/style/formatting.md @@ -0,0 +1,158 @@ +--- +title: Formatting guide +description: Formatting guidelines for technical documentation +keywords: formatting, style guide, contribute +toc_max: 2 +--- + +## Headings and subheadings + +As readers skip, skim and scan our pages, they often only notice the first two to three words of any of the paragraphs on the page. They also 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. + +The best headings should: + +- Let the reader know what they will find on the page. +- Describe succinctly and accurately what the content is about. +- Be creative, interesting, short (no more than eight words), to the point and written in plain, active language. +- Avoid puns, teasers and cultural references. +- Skip leading articles (a, the, etc) + +## Page title + +Try to make sure the title of your page is action orientated: + - enable SCIM + - Install Docker Desktop +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, you must wrap the entire title in “” to avoid breaking the build. + +## Images + +- Images, including screenshots, can help a reader better understand a concept. However, they should be used sparingly because they tend to go out-of-date quickly. +- 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. + + ### Images + +Don't forget to remove images that are no longer used. Keep the images sorted +in the local `images/` directory, with names that naturally group related images +together in alphabetical order. For example, use `settings-file-share.png` +and `settings-proxies.png` instead of `file-share-settings.png` and +`proxies-settings.png`. + +You may also use numbers, especially in the case of a +sequence, for example, `run-only-the-images-you-trust-1.svg`, +`run-only-the-images-you-trust-2.png`, `run-only-the-images-you-trust-3.png`. +When applicable, capture windows rather than the rectangular regions. This +eliminates unpleasant background and saves the editors the need to crop images. + +On Mac, capture windows without shadows. To do this, when you press +Command-Shift-4, press Option while clicking on the window. To disable shadows completely, run: + +```bash +$ defaults write com.apple.screencapture disable-shadow -bool TRUE +$ killall SystemUIServer # restart it. +``` + +You can restore the shadows later using `-bool FALSE`. + +To keep the Git repository light, _please_ compress the images +(losslessly). On Mac, you can use [ImageOptim](https://imageoptim.com) for +instance. 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, ut still optimizes the bandwidth during browsing). + + +## Links + +Be careful not to create too many links, especially within body copy. Excess links can be distracting or send readers away from the current page. + +When people follow links, they can often lose their train of thought and fail to return to the original page, despite not having absorbed all the information it contains. + +The best links offer readers another way to scan information. + +### Best practice: + +- Use plain language that does not 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. +- Follow conventions for naming common features (Read more, Next/Previous). +- 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. + +## Code and code samples + +- Format the following as code: docker commands, instructions and filenames (package names). +To apply inline code style, wrap the text in a single backtick (`). For example, this is inline code style + +To apply code block style, wrap the text in triple backticks (three `) and add a syntax highlighting hint. For example: + +```plaintext +This is codeblock style +``` + +When using code block style: + +Use quadruple backticks (four `) to apply code block style when the code block you are styling has triple backticks in it. For example, when illustrating code block style. +Add a blank line above and below code blocks. + +## Callouts + +Use callouts to emphasize selected information in a text. + +### Best practice: + +- Format the word Warning, Important, or Note in bold. Do not 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: +Note +Deleting a repository deletes all the images it contains and its build settings. This action cannot be undone. | | +| | | | + +## Navigation + +When documenting how to navigate through the Docker Desktop or Docker Hub UI: + +Always use location, then action. +From the Visibility dropdown list (location), select Public (action). +Be brief and specific. For example: +Do: Select Save. +Do not: 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 + +## Optional steps + +If a step is optional, start the step with the word Optional followed by a period. + +For example: + +1. Optional. Enter a description for the job. + +## Placeholder text + +You might want to provide a command or configuration that uses specific values. + +In these cases, use < and > to call out where a reader must replace text with their own value. + +## Tables + +Tables should be used 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. + +### 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. diff --git a/contribute/style/grammar.md b/contribute/style/grammar.md new file mode 100644 index 000000000000..847a729c8ea7 --- /dev/null +++ b/contribute/style/grammar.md @@ -0,0 +1,159 @@ +--- +title: Grammar and style +description: Grammar and style guidelines for technical documentation +keywords: grammar, style, contribute +toc_max: 2 +--- + +## Acronyms and initialisms + +An acronym is an abbreviation you would speak as a word, for example, ROM (for read only memory). Other examples include radar and scuba, which started out as acronyms but are now considered words in their own right. + +An initialism is a type of acronym that comprises a group of initial letters used as an abbreviation for a name or expression. If you were using the acronym in a spoken conversation, you would enunciate each letter: H-T-M-L for Hypertext Markup Language. + +### Best practice: + +- 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. +- 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. + +## Bolds and italics + +Unless you're referring to Ul text or user-defined text, you should not add emphasis to text. Clear, front-loaded wording makes the subject of a sentence clear. + +### Best practice: + +- Don't use bold to refer to a feature name. +- Use italics sparingly, as this type of formatting can be difficult to read in digital experiences. +Notable exceptions are titles of books, newspapers or magazines. + +## Capitalization + +Use sentence case for just about everything. Sentence case means capitalizing only the first word, as you would in a standard sentence. + +The following content elements should use sentence case: + +- Titles of webinars and events +- Headings and subheadings in all content types +- Calls to action +- Headers in boxed text +- Column and row headers in tables +- Links +- Sentences (of course) +- Anything in the Ul 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. +- 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). +- 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. + +## Contractions + +A contraction results from letters being left out from the original word or phrase, such as you're for you are or it's for it is. + +Following our conversational approach, it's acceptable to use contractions in almost all content types. Just don't get carried away. Too many contractions in a sentence can make it difficult to read. + +### Best practice: + +- Stay consistent - don't switch between contractions and their spelled-out equivalents in body copy or Ul 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. + +## Dates + +You should use the U.S. format of month day, year format for dates: June 26, 2021. + +When possible, use the month's full name (October 1, 2022). If there are space constraints, use 3-letter abbreviations followed by a period (Oct. 1. 2022). + +## Decimals and fractions + +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 + +Lists are a great way to break down complex ideas and make them easier to read and scan. + +### Best practice: + +- Bulleted lists should contain relatively few words or short phrases. For most content types, limit the number of items in a list to five. +- 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. +✅Example: + + I went to the shops to buy: + + - Milk + - Flour + - 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: + 1. Top level + 2. Top level + 1. Child step + 2. Child step + + +## Numbers + +When you work with numbers in content, the best practices include: + +- Spell out the numbers one to nine, except in units of measure such as 4 MB. +- Represent numbers with two or more digits as numerals (10, 625, 773,925). +- 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. +- 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. + + + | Correct ✅ | Incorrect ❌ | + | --- | --- | + | 1000 | 1,000 | + | 14 586 | 14,586 | + | 1 390 680 | 1,390,680 | + +### Versions + +When writing version numbers for release notes, follow the example below: + +Version 4.8.2 + +## Punctuation + +### 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. + +### Commas + +- Use the serial or Oxford comma - a comma before the coordinating conjunction (and, or) in a list of three or more things. +- If a series contains more than three items or the items are long, consider a bulleted list to improve readability. + +### Dashes and hyphens + +- Use the em dash (-) sparingly when you want the reader to pause, to create parenthetical statements, or to emphasize specific words or phrases. Always put a space on either side of the em dash. +- Use an en dash (-) to indicate spans of numbers, dates, or time. +- Use a hyphen to join two or more words to form compound adjectives that precede a noun. The purpose of joining words to form a compound adjective is to differentiate the meaning from the adjectives used separately (for example, ‘up-to-date documentation’ ‘lump-sum payment’, and ‘well-stocked cupboard’. You can also use a hyphen to: + - Avoid awkward doubling of vowels. For example ‘semi-independence*’,* or ‘re-elect’. + - Prevent misreading of certain words. For example ‘Re-collect’ means to collect again; without a hyphen the word recollect has a different meaning. + diff --git a/contribute/style/recommended-words.md b/contribute/style/recommended-words.md new file mode 100644 index 000000000000..78375378fe9f --- /dev/null +++ b/contribute/style/recommended-words.md @@ -0,0 +1,110 @@ +--- +title: Recommended word list +description: Recommended word list for Technical documentation +keywords: recommended word list, style guide, contribute +--- + +To help ensure consistency in the documentation, the Technical Writing team recommends these wording choices. + +#### above +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. + +#### below +Try to avoid below when referring to an example or table in a documentation page. If required, use following instead. + +#### checkbox + +Use one word for checkbox. Do not 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.  +Select applies to more devices, while click is more specific to a mouse. + +#### currently + +Do not use currently when talking about the product or its features. The documentation describes the product as it is today. + +#### delete + +We use delete in the UI + +#### deselect + +Don’t use deselect. Instead, use clear. + +#### earlier + +Use earlier when talking about version numbers. + +Use: + +In GitLab 14.1 and earlier. +Instead of: + +In GitLab 14.1 and lower. + +#### later +Use later when talking about version numbers. + +Use: + +In GitLab 14.1 and later… +Instead of: + +In GitLab 14.1 and higher… +In GitLab 14.1 and above… + +#### prerequisites + +#### register +Use register instead of sign up when talking about creating an account + +#### respectively +Avoid respectively and be more precise instead. + +Use: + +To create a user, select Create user. For an existing user, select Save changes. + +#### scroll + +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. + + +#### sign up +Use register or create account instead of sign up when talking about creating an account. + +#### toggle + +You turn on or turn off a toggle. For example: + +Turn on the blah toggle. + +#### update + +To repair or improve the product + + +#### upgrade +Use upgrade for: + +Choosing a higher subscription tier + +#### we + +Try to avoid we and focus instead on how the user can accomplish something in GitLab. + +Use: + +Use widgets when you have work you want to organize. +Instead of: + +We created a feature for you to add widgets. +One exception: You can use we recommend instead of it is recommended or GitLab recommends. \ No newline at end of file diff --git a/contribute/style/terminology.md b/contribute/style/terminology.md new file mode 100644 index 000000000000..08d0710632e7 --- /dev/null +++ b/contribute/style/terminology.md @@ -0,0 +1,60 @@ +--- +title: Docker terminology +description: Docker specific terminology and definitions +keywords: terminology, style guide, contribute +--- + +#### `compose.yaml` + +The current designation for the Compose file, as it is a file, format as code. + +#### Compose plugin + +The compose app 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. + +#### Docker Compose + +Use when we talk about the application, or all the functionality associated with the application. + +#### `docker compose` + +Use code formatting) for referring to the commands in text and command usage examples/code samples. + +#### Docker Compose CL + +Use when referring to family of Compose commands as offered from the Docker CLI. + +#### 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. + +#### Multi-architecture / multi-arch + +To use when referring specifically to CPU architecture or something that is hardware-architecture-based. Avoid using it as meaning the same as multi-platform. + +#### Member + +A user of Docker Hub that is a part of an organization + +#### Namespace + +Organization or User name. Every image needs a namespace to live under. + +#### Node + +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. + +#### Registry + +Online storage for Docker images. + +#### Repository + +Lets users share container images with their team, customers, or Docker community. + diff --git a/contribute/style/voice-tone.md b/contribute/style/voice-tone.md new file mode 100644 index 000000000000..08ee51fdbe30 --- /dev/null +++ b/contribute/style/voice-tone.md @@ -0,0 +1,53 @@ +--- +title: Voice and tone +description: Docker's voice and tone +keywords: style guide, voice, tone, content standards +--- + +# 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. + +We're not afraid to use a bit of cheeky humor to lighten the conversation (and because we don't take ourselves too seriously) but we're always respectful. We communicate with clarity, empathy, and wit; everything we say should inform and encourage. + +We align our tone of voice and content with our virtues. The most important principles we follow when we write are the 4Cs: + +1. **Correct** +2. **Concise** +3. **Complete** +4. **Clea**r + +We ensure the information is accurate, succinct, thorough, and easy to understand. We keep sentences as simple as possible, but include enough detail for the user to complete the intended task. + +All of this means that when we write documentation and UI copy: + +1. **We are honest.** We give you all the facts and we don't use misdirection or make ambiguous statements. We don't always have all the answers, but we're doing our best to make life better for developers and we'll tell you how it's going. +2. **We are concise.** We understand the industry of complex and detailed messaging our users live in because we come from the same world. Docker doesn't bulk up our communication with fluffy words or complex metaphors. We're clear and to the point. +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 + +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 + +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. + +**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. + +## Positive language + +Use a positive language. Instead of highlighting the limitations and what the users cannot do, emphasize on the positive outcomes. + +For example, **instead of**: + +“*Features such as Single Sign-on (SSO), Image Access Management, Registry Access Management are not available in Docker Team subscription.”* + +**Use**: + +“*Features such as Single Sign-on (SSO), Image Access Management, Registry Access Management are available in Docker Business subscription*.” + +# A Note About Moby + +Moby is Docker's mascot and is tightly tied into our history. Moby is a "blue whale" (the largest known animal to have ever existed!) and is gender-neutral. While Moby smiles and communicates with other facial expressions, they do not speak. Do not try to write in Moby's voice. Learn more about how to use Moby by reading through our usage guidelines. \ No newline at end of file diff --git a/contribute/template.md b/contribute/template.md new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/test.md b/test.md index dbda9d3f08e0..7deff169f9b5 100644 --- a/test.md +++ b/test.md @@ -1,6 +1,6 @@ --- description: Smoketest page -title: Testing page +title: Additional sitemap: false toc_min: 1 --- From ae8aad651b21734debd0c2f5ac395e738dfb2cc3 Mon Sep 17 00:00:00 2001 From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> Date: Thu, 11 Aug 2022 09:46:16 +0100 Subject: [PATCH 02/14] moved some content around --- README.md | 2 +- _data/toc.yaml | 1 + components.md | 860 ++++++++++++++++++++++++++++---- contribute/contribute-guide.md | 8 +- contribute/overview.md | 13 +- contribute/style/formatting.md | 38 +- contribute/style/voice-tone.md | 6 +- test.md | 867 --------------------------------- 8 files changed, 772 insertions(+), 1023 deletions(-) delete mode 100644 test.md diff --git a/README.md b/README.md index 3a04e5ebc715..0b4d87d98c9d 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ We've made it really easy for you to file new issues. We value your contribution. We'd like to make it as easy as possible to submit your contributions to the Docker docs repository. Changes to the docs are handled through pull requests against the `master` branch. To learn how to -contribute, see [CONTRIBUTING.md](CONTRIBUTING.md). +contribute, see our [Contribute section](contribute/overview.md). ## Copyright and license diff --git a/_data/toc.yaml b/_data/toc.yaml index d12586d4aa2e..08013761c009 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -1659,6 +1659,7 @@ contribute: - path: /contribute/overview/ title: Contribute to Docker's docs - path: /contribute/contribute-guide/ + title: Contribution guidelines - sectiontitle: Style guide section: - path: /contribute/style/grammar/ diff --git a/components.md b/components.md index 36147964582b..4abd2663244f 100644 --- a/components.md +++ b/components.md @@ -1,136 +1,784 @@ --- -description: Components page -title: Useful components -sitemap: false +description: components and formatting examples used in Docker's docs +title: Useful components and formatting examples --- +This is a demo of components, tags, styles, tools, and strategies we use for the +docs. We explain the code behind the published page and demo the effects. For components and controls we are using [Bootstrap](https://getbootstrap.com) -### Tooltips +## Links and images - +### Links - +- [a markdown link](https://docker.com/) +- [a markdown link that opens in a new window](https://docker.com/){: target="_blank" rel="noopener" class="_" } +- [a markdown link to a custom target ID](#custom-target-id) - +- an HTML link - +- an HTML link that opens in a new window +- A link to a Github PR in `docker/docker`: {% include github-pr.md pr=28199 %} +- A link to a Github PR in `docker/docker.github.io`: {% include github-pr.md repo=docker.github.io pr=9999 %} -#### HTML + - You can specify `org=foo` to use a Github organization other than Docker -```html - +- 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 `docker.github.io` + 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 + **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 + from the URL, and use that as the link in your docs file. - + - Keep in mind that this link doesn't resolve until you merge the PR and + your docs are published on [docs.docker.com](/). + +{: id="custom-target-id"} + +#### Using a custom target ID + +This topic has a custom target ID above its heading that can be used to link to +it, in addition to, or instead of, the default concatenated heading style. The +format of this ID is `{: id="custom-target-id"}`. + +You can use custom targets to link to headings or even paragraphs. You link to +it as you would any other link, using `#custom-target-id` as the ultimate +target. + +An example of a custom target ID in the documentation is the topic on +[Compose file version 2 topic on CPU and other resources](compose/compose-file/compose-file-v2.md#cpu-and-other-resources). +It has a long heading that breaks the normal Markdown linking mechanism, +so we added a custom ID above the target heading. + +### Images + +- A small cute image: ![a small cute image](/images/footer_moby_icon.png) + +- A small cute image that is a link. The extra newline here makes it not show + inline: + + [![a small cute image](/images/footer_moby_icon.png)](https://www.docker.com/) + +- A big wide image: ![a pretty wide image](/images/banner_image_24512.png) + +- The same as above but using HTML: a pretty wide image using HTML + +[Some Bootstrap image classes](https://getbootstrap.com/docs/3.4/css/#images){: target="_blank" rel="noopener" class="_" } +might be interesting. You can use them with Markdown or HTML images. + +- An image using the Bootstrap "thumbnail" class: ![an image as a thumbnail](/images/footer_moby_icon.png){: class="img-thumbnail" } + +- The same one, but using HTML: a pretty wide image as a thumbnail, using HTML + +## Videos + +To embed a YouTube video on a docs page, open the video on YouTube, click +**Share** > **Embed** and then copy the code displayed. + +For example, the video embedded on the Get Started page has the following code: + +```html + ``` +You can also add a link to a YouTube video like this: + +[Docker 101: Introduction to Docker](https://www.youtube.com/watch?v=V9IJj4MzZBc "Docker 101: Introduction to Docker"){:target="_blank" rel="noopener" class="_"} + +To make the `.png` shown above, first take a screen snap of the YouTube video +you want to use, then use a graphics app to overlay a play button onto the +image. + +For the overlay, you can use the play button at +[/docker-cloud/images/](https://github.com/docker/docker.github.io/tree/master/docker-cloud/images). + +## Lists + +- Bullet list item 1 +- Bullet list item 2 +* Bullet list item 3 + +1. Numbered list item 1. Two spaces between the period and the first letter + helps with alignment. + +2. Numbered list item 2. Let's put a note in it. + + >**Note**: We did it! + +3. Numbered list item 3 with a code block in it. You need the blank line before + the code block happens. + + ```bash + $ docker run hello-world + ``` + +4. Numbered list item 4 with a bullet list inside it and a numbered list + inside that. + + - Sub-item 1 + - Sub-item 2 + 1. Sub-sub-item 1 + 2. Sub-sub-item-2 with a table inside it because we like to party! + Indentation is super important. + + |Header 1 | Header 2 | + |---------|----------| + | Thing 1 | Thing 2 | + | Thing 3 | Thing 4 | + +## Tables + +Some tables in markdown and html. + +| Permission level | Access | +|:-------------------------------------------------------------------------|:-------------------------------------------------------------| +| **Bold** or _italic_ within a table cell. Next cell is empty on purpose. | | +| | Previous cell is empty. A `--flag` in mono text. | +| Read | Pull | +| Read/Write | Pull, push | +| Admin | All of the above, plus update description, create, and delete | + +The alignment of the cells in the source doesn't really matter. The ending pipe +character is optional (unless the last cell is supposed to be empty). The header +row and separator row are optional. + +If you need block-level HTML within your table cells, such as multiple +paragraphs, lists, sub-tables, etc, then you need to make a HTML table. +This is also the case if you need to use rowspans or colspans. Try to avoid +setting styles directly on your tables! If you set the width on a ``, you +only need to do it on the first one. If you have a ``, set it there. + +> **Note**: If you need to have **markdown** in a **HTML** table, add +> `markdown="span"` to the HTML for the `` cells that contain the Markdown. + + + + + + + + + + + + + + +
Left channelRight channel
This is some test text.

This is more text on a new line.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. + 		This is some more text about the right hand side. There is a link here to the Docker Experimental Features README on GitHub. In tables, links need to be ``.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+

Go to the docs!

+

It is dark here. You are likely to be eaten by a grue.

+ 		+

Go to the docs!

+

It is dark here. You are likely to be eaten by a grue.

+
+ +## Glossary links and content + +The glossary source lives in the documentation repository +[docker.github.io](https://github.com/docker/docker.github.io) in +`_data/glossary.yaml`. The glossary publishes to +[https://docs.docker.com/glossary/](/glossary/). + +To update glossary content, edit `_data/glossary.yaml`. + +To link to a glossary term, link to `glossary.md#YourGlossaryTerm` (for +example, [swarm](glossary.md#swarm)). + +## Mixing Markdown and HTML + +You can use span-level HTML tags within Markdown. + +You can use a `
` tag to impose an extra newline like here:
+ +You can use entities like ` ` to keep a bunch of words together . + +
+You can use block-level HTML tags too. This paragraph is centered. +
+ +Keep reading for more examples, such as creating tabbed content within the +page or displaying content as "cards". + +## Jekyll / Liquid tricks + +### Assignment + +This paragraph is centered and colored green by setting CSS directly on the element. +**Even though you can do this and it's sometimes the right way to go, remember that if +we re-skin the site, any inline styles need to be dealt with manually!** +{: style="text-align:center; color: green" } + +{% assign my-text="foo" %} + +The Liquid assignment just before this line fills in the following token {{ my-text }}. +This is effective for the rest of this file unless the token is reset. + +{% capture my-other-text %}foo{% endcapture %} +Here is another way: {{ my-other-text }} + +You can nest captures within each other to represent more complex logic with Liquid. + +### Liquid variable scope + +- Things set in the top level of `_config.yml` are available as site variables, like `{{ site.debug }}`. +- Things set in the page's metadata, either via the defaults in `_config.yml` or per page, are available as page variables, like `{{ page.title }}`. +- In-line variables set via `assign` or `capture` are available for the remainder of the page after they are set. +- If you include a file, you can pass key-value pairs at the same time. These are available as include variables, like `{{ include.toc_min }}`. + +## Bootstrap and CSS tricks + +Here are cool components you can include on Docs pages using +[Bootstrap](https://getbootstrap.com) and [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS). + +### Tabs + +Here are some tabs: + + +
+
TAB 1 CONTENT
+
TAB 2 CONTENT
+
+ +You need to adjust the `id` and `data-target` values to match your use case. + +The `
`'s are included simply to add visual separation between tabbed content +and the other topics on the page. + +If you have Markdown inside the content of the `
`, just add `markdown="1"` +as an attribute in the HTML for the `
` so that Kramdown renders it. + + +
+
+ +#### A Markdown header + +- list item 1 +- list item 2
+
+
- +#### Synchronizing multiple tab groups +Consider an example where you have something like one tab per language, and +you have multiple tab sets like this on a page. You might want them to all +toggle together. We have Javascript that loads on every page that lets you +do this by setting the `data-group` attributes to be the same. The +`data-target` attributes still need to point to unique div IDs. -### Accordion -[Bootstrap docs](https://getbootstrap.com/docs/3.4/javascript/) -
-
- -
-
- Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS. -
-
-
-
- -
-
- Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS. -
-
-
-
- -
-
- Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS. -
-
-
+In this example, selecting `Go` or `Python` in one tab set toggles the +other tab set to match. + + +
+
Go content here
+
Python content here
-#### HTML +And some content between the two sets, just for fun... -```html -
-
- -
-
- Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS. -
-
-
-
- -
-
- Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS. -
-
-
-
- -
-
- Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS. -
+ +
+
Go content here
+
Python content here
+
+ +### Cards + +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. You need a couple `
`s +to clear the row before.

+ +
+
This takes up 1/3 of the row unless the screen is small, +then it takes up the whole row.
+
This takes up 1/3 of the row unless the screen is small, +then it takes up the whole row.
+
This takes up 1/3 of the row unless the screen is small, +then it takes up the whole row.
+
+ +### Expand/Collapse accordions + +You can use the Bootstrap and CSS to add expand/collapse accordions. This +implementation makes use of the `.panel-heading` classes in +[`_utilities.scss`](https://github.com/docker/docker.github.io/blob/master/_scss/_utilities.scsss), +along with [FontAwesome icons](http://fontawesome.io/cheatsheet/){: target="_blank" rel="noopener" class="_" } + (fa-caret-down) and + (fa-caret-up). + +Adding `block` to the `div` class `collapse` gives you some padding around the +sample content. This works nicely for standard text. If you have a code sample, +the padding renders as white space around the code block grey background. If we +don't like this effect, we can remove `block` for code samples. + +The `style="cursor: pointer"` tag enables the expand/collapse functionality to +work on mobile. (You can use the [Xcode iPhone simulator](https://developer.apple.com/library/content/documentation/IDEs/Conceptual/iOS_Simulator_Guide/GettingStartedwithiOSSimulator/GettingStartedwithiOSSimulator.html#//apple_ref/doc/uid/TP40012848-CH5-SW4){: target="_blank" rel="noopener" class="_" } to test on mobile.) + +There are a lot of samples out there for Bootstrap accordions. This is the model +we used: [PPxOJX accordion sample with HTML and +CSS](https://codepen.io/anon/pen/PPxOJX){: target="_blank" rel="noopener" class="_" }. (Here is +another example, but it uses Javascript, whereas the implementation shown +[here](https://www.bootply.com/89084){: target="_blank" rel="noopener" class="_" } is Bootstrap +and CSS only.) + +> Make sure `data-target`'s and `id`'s match, and are unique +> +>For each drop-down, the value for `data-target` and +`collapse` `id` must match, and id's must be unique per page. In this example, +we name these `collapseSample1` and `collapseSample2`. Check out the +[Compose file structure example](compose/compose-file/compose-file-v3.md#compose-file-structure-and-examples) +to see another example. +{: .important-vanilla} + +
+ +
+

+$ docker run hello-world
+Unable to find image 'hello-world:latest' locally
+latest: Pulling from library/hello-world
+2db29710123e: Pull complete
+Digest: sha256:cc15c5b292d8525effc0f89cb299f1804f3a725c8d05e158653a563f15e4f685
+Status: Downloaded newer image for hello-world:latest
+
+Hello from Docker!
+This message shows that your installation appears to be working correctly.
+
+To generate this message, Docker took the following steps:
+
+1. The Docker client contacted the Docker daemon.
+2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
+    (amd64)
+3. The Docker daemon created a new container from that image which runs the
+4. The Docker daemon streamed that output to the Docker client, which sent it
+    to your terminal.
+
+To try something more ambitious, you can run an Ubuntu container with:
+
+$ docker run -it ubuntu bash
+
+Share images, automate workflows, and more with a free Docker ID:
+ https://hub.docker.com/
+
+For more examples and ideas, visit:
+ https://docs.docker.com/get-started/
+
+ +
+

+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor +incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis +nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. +Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu +fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in +culpa qui officia deserunt mollit anim id est laborum.

-``` \ No newline at end of file + +### Columnar text + +You can use the CSS `column-count` to flow your text into multiple columns. +You need a couple `
`s to clear the row before.

+ +
+This example uses a HTML div. This example uses a HTML div. This example uses a HTML div. +This example uses a HTML div. This example uses a HTML div. This example uses a HTML div. +This example uses a HTML div. This example uses a HTML div. This example uses a HTML div. +This example uses a HTML div. This example uses a HTML div. This example uses a HTML div. +This example uses a HTML div. This example uses a HTML div. This example uses a HTML div. +This example uses a HTML div. This example uses a HTML div. This example uses a HTML div. +This example uses a HTML div. This example uses a HTML div. This example uses a HTML div. +This example uses a HTML div. This example uses a HTML div. This example uses a HTML div. +This example uses a HTML div. This example uses a HTML div. This example uses a HTML div. +
+ +This example does it with Markdown. You can't have any blank lines or it breaks the Markdown block up. +This example does it with Markdown. You can't have any blank lines or it breaks the Markdown block up. +This example does it with Markdown. You can't have any blank lines or it breaks the Markdown block up. +This example does it with Markdown. You can't have any blank lines or it breaks the Markdown block up. +This example does it with Markdown. You can't have any blank lines or it breaks the Markdown block up. +This example does it with Markdown. You can't have any blank lines or it breaks the Markdown block up. +This example does it with Markdown. You can't have any blank lines or it breaks the Markdown block up. +{: style="column-count: 3 "} + +### Badges + +You can have badges. You can also have +yellow badges or +red badges. + +#### Badges as links + +You can make a badge a link. Wrap the `` with an `` (not the other way +around) so that the text on the badge is still white. + +```html +Test +``` + +Test + + +You can also put tooltips on badges (as the example above shows). Keep reading for tooltips. + +### Tooltips + +To add a tooltip to any element, set `data-toggle="tooltip"` and set a `title`. +Hovering over the element with the mouse pointer will make it visible. Tooltips +are not visible on mobile devices or touchscreens, so don't rely on them as the +only way to communicate important info. + +```html +Test +``` +or + + + + + + + + + + +Test + +You can optionally set the `data-placement` attribute to `top`, `bottom`, +`middle`, `center`, `left`, or `right`. Only set it if not setting it causes +layout issues. + +You don't have to use HTML. You can also set these attributes using Markdown. + +```markdown +This is a paragraph that has a tooltip. We position it to the left so it doesn't align with the middle top of the paragraph (that looks weird). +{:data-toggle="tooltip" data-placement="left" title="Markdown tooltip example"} +``` + +This is a paragraph that has a tooltip. We position it to the left so it doesn't align with the middle top of the paragraph (that looks weird). +{:data-toggle="tooltip" data-placement="left" title="Markdown tooltip example"} + +## Running in-page Javascript + +If you need to run custom Javascript within a page, and it depends upon JQuery +or Bootstrap, make sure the `