chore: refactor style guide to STYLE.md and COMPONENTS.md

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

STYLE.md

@@ -0,0 +1,566 @@
+# Docker Documentation Style Guide
+
+This guide consolidates voice, grammar, formatting, and terminology
+standards for Docker documentation. Follow these guidelines to create
+clear, consistent, and helpful content. For instructions on how to use
+components, shortcodes, and other features, see [COMPONENTS.md](COMPONENTS.md).
+
+## Voice and tone
+
+Write like a knowledgeable colleague explaining something useful. We're
+developers writing for developers.
+
+### Core principles: The 4Cs
+
+1. **Correct** - Information is accurate
+2. **Concise** - Succinct without unnecessary words
+3. **Complete** - Includes enough detail to complete the task
+4. **Clear** - Easy to understand
+
+### Writing approach
+
+- **Be honest.** Give all the facts. Don't use misdirection or
+  ambiguous statements.
+- **Be concise.** Don't bulk up communication with fluffy words or
+  complex metaphors. Get to the point.
+- **Be relaxed.** Casual but not lazy, smart but not arrogant, focused
+  but not cold. Be welcoming and warm.
+- **Be inclusive.** Every person is part of our community, regardless
+  of experience level.
+
+### Tone guidelines
+
+- Use a natural, friendly, and respectful tone
+- Use contractions to sound conversational (it's, you're, don't)
+- Avoid overdoing politeness - skip "please" in most technical documentation
+- Be clear over comical
+- Use positive language - emphasize what users can do, not what they can't
+
+**Positive language 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."
+
+### Avoiding marketing language
+
+Documentation should be factual and direct, not promotional.
+
+**Avoid hedge words** that overstate ease or capability:
+
+- ❌ simply, just, easily, seamlessly (implies ease when it may not be
+  easy)
+- ❌ robust, powerful (marketing language)
+- ✅ Instead: describe what it actually does
+
+**Avoid excessive enthusiasm:**
+
+- ❌ "powerful feature", "game-changing", "revolutionary", "amazing"
+- ✅ Instead: describe the feature and its benefits factually
+
+**Avoid meta-commentary:**
+
+These phrases add no value - state the fact directly:
+
+- ❌ "It's worth noting that..."
+- ❌ "It's important to understand that..."
+- ❌ "Keep in mind that..."
+- ✅ Instead: state the information directly
+
+### Voice and perspective
+
+- **Use "you" not "we"**: Focus on what the user can do, not what "we"
+  created
+  - ❌ "We provide a feature that helps you deploy"
+  - ✅ "Deploy your applications with..."
+- **Avoid "please"**: Don't use in normal explanations or "please note"
+  phrases
+- **Write timelessly**: Avoid "currently" or "as of this writing" - the
+  documentation describes the product as it is today
+
+### Scope preservation
+
+When updating existing documentation, resist the urge to expand
+unnecessarily. Users value brevity.
+
+**Understand the current document:**
+Read it fully to grasp its scope, length, and character. Is it a minimal
+how-to or a comprehensive reference?
+
+**Match the existing character:**
+If the document is brief and direct (90 lines), keep it that way. Don't
+transform a focused guide into an exhaustive tutorial.
+
+**Add only what's genuinely missing:**
+Fill gaps, don't elaborate. If the document already covers a topic
+adequately, don't expand it.
+
+**Value brevity:**
+Say what needs to be said, then stop. Not every topic needs
+prerequisites, troubleshooting, best practices, and examples sections.
+
+**Respect the original intent:**
+The document exists in its current form for a reason. Improve it, don't
+remake it.
+
+Good additions fill genuine gaps. Bad additions change the document's
+character. When in doubt, add less rather than more.
+
+## Grammar and style
+
+Write in US English with US grammar.
+
+### Acronyms and initialisms
+
+- Spell out lesser-known acronyms on first use, then follow with the
+  acronym in parentheses: "single sign-on (SSO)"
+- Don't spell out common acronyms like URL, HTML, API
+- Use all caps for file type acronyms: JPEG, PNG
+- Don't use apostrophes for plurals: URLs not URL's
+- Avoid introducing acronyms in headings - introduce them in the body
+  text that follows
+
+### Capitalization
+
+Use sentence case for almost everything: headings, titles, links, buttons,
+navigation labels.
+
+- Capitalize Docker solutions: Docker Desktop, Docker Hub, Docker Extensions
+- Capitalize job titles only when they immediately precede a name:
+  "Chief Executive Officer Scott Johnston" but "Scott Johnston, chief
+  executive officer"
+- Follow company capitalization preferences: DISH, bluecrux
+- Match UI capitalization when referring to specific interface elements
+
+### Contractions
+
+Use contractions to maintain a conversational tone, but don't overdo it.
+
+- Stay consistent - don't switch between "you are" and "you're" in the
+  same content
+- Avoid negative contractions when possible (can't, don't, won't) -
+  rewrite to be positive
+- Never contract a noun with a verb (your container is ready, not your
+  container's ready)
+
+### Dangling modifiers
+
+Avoid unclear subjects:
+
+- ❌ After enabling auto-log-out, your users are logged out
+- ✅ When you enable auto-log-out, your users are logged out
+
+### Dates and numbers
+
+- Use US date format: June 26, 2021 or Jun. 26, 2021
+- Spell out numbers one through nine, except in units: 4 MB
+- Use numerals for 10 and above: 10, 625, 1000
+- Use decimals instead of fractions: 0.5 not ½
+- For numbers with five or more digits, use spaces instead of commas:
+  14 586 not 14,586
+- For version numbers: version 4.8.2, v1.0, Docker Hub API v2
+
+### Punctuation
+
+- **Commas:** Use the Oxford comma (serial comma) in lists
+- **Colons:** Use to introduce lists or provide explanations
+- **Semicolons:** Don't use - write two sentences instead
+- **Em dashes:** Use sparingly with spaces on either side: "text - like
+  this - text"
+- **Hyphens:** Use for compound adjectives before nouns:
+  "up-to-date documentation"
+- **Exclamation marks:** Avoid
+- **Parentheses:** Avoid in technical documentation - they reduce
+  readability
+
+### Conciseness and redundant phrases
+
+Remove unnecessary words to make documentation clearer and more direct.
+
+**Eliminate redundant phrases:**
+
+- ❌ "in order to" → ✅ "to"
+- ❌ "serves the purpose of" → ✅ state what it does directly
+- ❌ "allows you to" → ✅ "lets you" or state what it does
+- ❌ "enables you to" → ✅ "lets you" or state what it does
+
+### Bold and italics
+
+Use bold **only** for UI elements (buttons, menus, field labels). Never
+use bold for emphasis, product names, or feature names.
+
+- ✅ Select **Save** (UI button - use bold)
+- ✅ Docker Hub provides storage (product name - no bold)
+- ✅ This is important to understand (emphasis - no bold)
+- ❌ **Docker Desktop** is a tool (product name - don't bold)
+- ❌ This is **very important** (emphasis - don't bold)
+- ❌ The **build** command (command name - don't bold)
+
+**Italics:**
+Use italics sparingly, as this formatting can be difficult to read in
+digital experiences. Notable exceptions are titles of articles, blog
+posts, or specification documents.
+
+## Formatting
+
+### Content types and detail balance
+
+Different content types require different writing approaches. Match your
+style and detail level to the content type.
+
+**Getting Started / Tutorials:**
+
+- Step-by-step instructions
+- Assume beginner knowledge
+- Explain _why_ at each step
+- Include more context and explanation
+
+**How-to Guides:**
+
+- Task-focused and goal-oriented
+- Assume intermediate knowledge
+- Focus on _how_ efficiently
+- Less explanation, more direct steps
+
+**Reference Documentation:**
+
+- Comprehensive and exhaustive
+- Assume advanced knowledge
+- Focus on _what_ precisely
+- Complete parameter lists and options
+
+**Concept Explanations:**
+
+- Educational and foundational
+- Any skill level
+- Focus on _understanding_ over doing
+- Theory before practice
+
+**Match detail to context:**
+
+- **First mention** of a concept: explain it
+- **Subsequent mentions**: link to the explanation or use the term
+  directly if recently explained
+- **Common knowledge** (to your audience): state it, don't explain it
+- **Edge cases**: mention them but don't let them dominate the main flow
+
+### Headings
+
+- Keep headings short (no more than eight words)
+- Front-load the most important words
+- Use descriptive, action-oriented language
+- Skip leading articles (a, the)
+- Avoid puns, teasers, and cultural references
+- Page titles should be action-oriented: "Install Docker Desktop",
+  "Enable SCIM"
+
+### Page structure and flow
+
+Every page should answer two questions in the first paragraph:
+
+1. **What will I learn?** - State what the page covers
+2. **Why does this matter?** - Explain the benefit or use case
+
+**Good opening:**
+
+```markdown
+Docker Compose Watch automatically updates your running containers when
+you change code. This eliminates the manual rebuild-restart cycle during
+development.
+```
+
+**Weak opening:**
+
+```markdown
+Docker Compose Watch is a powerful feature that enables developers to
+streamline their development workflow by providing automatic
+synchronization capabilities.
+```
+
+**Transitions and flow:**
+Connect ideas naturally. Each section should flow logically from the
+previous one. Save detailed discussions for after showing basic usage -
+don't front-load complexity.
+
+**Good flow:**
+
+1. Prerequisites
+2. Basic usage (show the simple case first)
+3. Advanced options (add complexity after basics are clear)
+
+**Jarring flow:**
+
+1. Prerequisites
+2. Overview of all capabilities (too much before seeing it work)
+3. Basic usage
+
+**Avoid structural problems:**
+
+- Don't start multiple sentences or sections with the same structure
+  (varies pacing and improves readability)
+- Don't over-explain obvious things (trust the reader's competence)
+- Don't use "**Bold:** format" for subsection labels (use plain text
+  with colon)
+
+### Lists
+
+- Limit bulleted lists to five items when possible
+- Don't add commas or semicolons to list item ends
+- Capitalize list items for ease of scanning
+- Make all list items parallel in structure
+- Start each item with a capital letter unless it's a parameter or
+  command
+- For nested sequential lists, use lowercase letters: 1. Top level,
+  a. Child step
+
+**Avoid marketing-style list formatting:**
+
+Don't use "**Term** - Description" format, which reads like marketing
+copy:
+
+❌ **Bad example:**
+
+- **Build** - Creates images from Dockerfiles
+- **Run** - Starts containers from images
+- **Push** - Uploads images to registries
+
+✅ **Good alternatives:**
+
+Use simple descriptive bullets:
+
+- Build images from Dockerfiles
+- Start containers from images
+- Upload images to registries
+
+Or use proper prose when appropriate:
+"Docker lets you build images from Dockerfiles, start containers from
+images, and upload images to registries."
+
+### Code and commands
+
+Format Docker commands, instructions, filenames, and package names as
+inline code using backticks: `docker build`
+
+**Code example pattern:**
+
+Follow this three-step pattern for code examples:
+
+1. **State** what you're doing (brief)
+2. **Show** the command or code
+3. **Explain** the result or key parts (if not obvious)
+
+**Example:**
+
+````markdown
+Build your image:
+
+```console
+$ docker build -t my-app .
+```
+
+This creates an image tagged `my-app` using the Dockerfile in the
+current directory.
+````
+
+**When to show command output:**
+
+- Show output when it helps understanding
+- Show output when users need to verify results
+- Don't show output for commands with obvious results
+- Don't show output when it's not relevant to the point
+
+For code block syntax, language hints, variables, and advanced features
+(line highlighting, collapsible blocks), see
+[COMPONENTS.md](COMPONENTS.md#code-blocks).
+
+### Links
+
+- Use plain, descriptive language (around five words)
+- Front-load important terms at the beginning
+- Avoid generic calls to action like "click here" or "find out more"
+- Don't include end punctuation in link text
+- Use relative links with source filenames for internal links
+- Don't make link text bold or italic unless it would be in normal
+  body copy
+
+### Images
+
+**Best practices:**
+
+- Capture only relevant UI - don't include unnecessary white space
+- Use realistic text, not lorem ipsum
+- Keep images small and focused
+- Compress images before adding to repository
+- Remove unused images from repository
+
+For image syntax and parameters (sizing, borders), see
+[COMPONENTS.md](COMPONENTS.md#images).
+
+### Callouts
+
+Use callouts sparingly to emphasize important information. Use them only
+when information truly deserves special emphasis - for warnings, critical
+notes, or important context that affects how users approach a task.
+
+Callout types: Note (informational), Tip (helpful suggestion), Important
+(moderate issue), Warning (potential damage/loss), Caution (serious risk).
+
+For syntax and detailed usage guidelines, see
+[COMPONENTS.md](COMPONENTS.md#callouts).
+
+### Tables
+
+- Use sentence case for table headings
+- Don't leave cells empty - use "N/A" or "None" if needed
+- Align decimals on the decimal point
+
+### Navigation instructions
+
+- Use location, then action: "From the **Visibility** drop-down list, select Public"
+- Be brief and specific: "Select **Save**"
+- Start with the reason if a step needs one: "To view changes, select the link"
+
+### Optional steps
+
+Start optional steps with "Optional." followed by the instruction:
+
+_1. Optional. Enter a description for the job._
+
+### File types and units
+
+- Use formal file type names: "a PNG file" not "a .png file"
+- Use abbreviated units with spaces: "10 GB" not "10GB" or
+  "10 gigabytes"
+
+## Word list
+
+### Recommended terms
+
+| Use                                   | Don't use              |
+| ------------------------------------- | ---------------------- |
+| lets                                  | allows                 |
+| turn on, toggle on                    | enable                 |
+| turn off, toggle off                  | disable                |
+| select                                | click                  |
+| following                             | below                  |
+| previous                              | above                  |
+| checkbox                              | check box              |
+| username                              | account name           |
+| sign in                               | sign on, log in, login |
+| sign up, create account               | register               |
+| for example, such as                  | e.g.                   |
+| run                                   | execute                |
+| want                                  | wish                   |
+| Kubernetes                            | K8s                    |
+| repository                            | repo                   |
+| administrator (first use), admin (UI) | -                      |
+| and                                   | & (ampersand)          |
+| move through, navigate to             | scroll                 |
+| (be more precise)                     | respectively           |
+| versus                                | vs, vs.                |
+| use                                   | utilize                |
+| help                                  | facilitate             |
+
+### Version numbers
+
+- Use "earlier" not "lower": Docker Desktop 4.1 and earlier
+- Use "later" not "higher" or "above": Docker Desktop 4.1 and later
+
+### Quick transformations
+
+Common phrases to transform for clearer, more direct writing:
+
+| Instead of...            | Write...                     |
+| ------------------------ | ---------------------------- |
+| In order to build        | To build                     |
+| This allows you to build | This lets you build / Build  |
+| Simply run the command   | Run the command              |
+| We provide a feature     | Docker provides / You can    |
+| Utilize the API          | Use the API                  |
+| This facilitates testing | This helps test / This tests |
+| Click the button         | Select the button            |
+| It's worth noting that X | X (state it directly)        |
+
+### UI elements
+
+- **tab vs view** - Use "view" for major UI sections, "tab" for
+  sub-sections
+- **toggle** - You "turn on" or "turn off" a toggle
+
+## Docker terminology
+
+### Products and features
+
+- **Docker Compose** - The application or all functionality associated
+  with it
+- **`docker compose`** - Use code formatting for commands
+- **Docker Compose CLI** - The family of Compose commands from
+  Docker CLI
+- **Compose plugin** - The add-on for Docker CLI that can be
+  enabled/disabled
+- **compose.yaml** - Current designation for the Compose file (use
+  code formatting)
+
+### Technical terms
+
+- **Digest** - Long string automatically created when you push an
+  image
+- **Member** - A user of Docker Hub who is part of an organization
+- **Namespace** - Organization or user name; every image needs a
+  namespace
+- **Node** - Physical or virtual machine running Docker Engine in
+  swarm mode
+  - Manager nodes: Perform swarm management and orchestration
+  - Worker nodes: Execute tasks
+- **Registry** - Online storage for Docker images
+- **Repository** - Lets users share container images with team,
+  customers, or community
+
+### Platform terminology
+
+- **Multi-platform** - Broad: Mac/Linux/Windows; Narrow: Linux/amd64
+  and Linux/arm64
+- **Multi-architecture (multi-arch)** - CPU architecture or
+  hardware-architecture-based; don't use as synonym for multi-platform
+
+## Quick reference
+
+### Voice checklist
+
+- ✅ Direct and practical
+- ✅ Conversational with active voice
+- ✅ Specific and actionable
+- ❌ Corporate-speak
+- ❌ Condescending
+- ❌ Overly formal
+
+### Structure checklist
+
+- ✅ Answer "What will I learn?" in the first paragraph
+- ✅ Answer "Why does this matter?" in the first paragraph
+- ✅ Front-load important information in headings and lists
+- ✅ Connect ideas naturally between sections
+- ✅ Use examples to clarify concepts
+- ✅ Match content type (tutorial vs how-to vs reference vs concept)
+- ✅ Follow code example pattern: state → show → explain
+- ✅ Preserve document scope (don't unnecessarily expand)
+
+### Common mistakes
+
+- ❌ Using "click" instead of "select"
+- ❌ Using "below" instead of "following"
+- ❌ Starting sentences with numbers (recast the sentence)
+- ❌ Using apostrophes in plural acronyms
+- ❌ Leaving table cells empty
+- ❌ Using commas in large numbers (use spaces)
+- ❌ Referring to file types by extension (.png file)
+- ❌ Using bold for product names or emphasis (only for UI elements)
+- ❌ Using "**Term** - Description" format in lists
+- ❌ Using hedge words (simply, easily, just, seamlessly)
+- ❌ Using meta-commentary (it's worth noting that...)
+- ❌ Using "we" instead of "you" or "Docker"
+- ❌ Showing command output when it's not needed
+- ❌ Not explaining what users will learn in first paragraph