tooling: add prompts to vscode

Author: ArthurFlag

.github/instructions/styleguide-instructions.md

@@ -0,0 +1,111 @@
+---
+applyTo: '**/*.md'
+---
+# Documentation Writing Instructions
+
+These are our documentation writing style guidelines.
+
+## General Style tips
+
+* Get to the point fast.
+* Talk like a person.
+* Simpler is better.
+* Be brief. Give customers just enough information to make decisions confidently. Prune every excess word.
+* We use Hugo to generate our docs.
+
+## Grammar
+
+* Use present tense verbs (is, open) instead of past tense (was, opened).
+* Write factual statements and direct commands. Avoid hypotheticals like "could" or "would".
+* Use active voice where the subject performs the action.
+* Write in second person (you) to speak directly to readers.
+* Use gender-neutral language.
+* Avoid multiple -ing words that can create ambiguity.
+* Keep prepositional phrases simple and clear.
+* Place modifiers close to what they modify.
+
+## Capitalization
+
+* Use sentence-style capitalization for everything except proper nouns.
+* Always capitalize proper nouns.
+* Don’t capitalize the spelled-out form of an acronym unless it's a proper noun.
+* In programming languages, follow the traditional capitalization of keywords and other special terms.
+* Don't use all uppercase for emphasis.
+
+## Numbers
+
+* Spell out numbers for zero through nine, unless space is limited. Use numerals for 10 and above.
+* Spell out numbers at the beginning of a sentence.
+* Spell out ordinal numbers such as first, second, and third. Don't add -ly to form adverbs from ordinal numbers.
+
+## Punctuation
+
+* Use short, simple sentences.
+* End all sentences with a period.
+* Use one space after punctuation marks.
+* After a colon, capitalize only proper nouns.
+* Avoid semicolons - use separate sentences instead.
+* Use question marks sparingly.
+* Don't use slashes (/) - use "or" instead.
+
+## Text formatting
+
+* UI elements, like menu items, dialog names, and names of text boxes, should be in bold text.
+* Use code style for:
+    * Code elements, like method names, property names, and language keywords.
+    * SQL commands.
+    * Command-line commands.
+    * Database table and column names.
+    * Resource names (like virtual machine names) that shouldn't be localized.
+    * URLs that you don't want to be selectable.
+* For code placeholders, if you want users to replace part of an input string with their own values, use angle brackets (less than < and greater than > characters) on that placeholder text.
+* Don't apply an inline style like italic, bold, or inline code style to headings.
+
+## Alerts
+
+* Alerts are a Markdown extension to create block quotes that render with colors and icons that indicate the significance of the content. The following alert types are supported:
+
+    * `[!NOTE]` Information the user should notice even if skimming.
+    * `[!TIP]` Optional information to help a user be more successful.
+    * `[!IMPORTANT]` Essential information required for user success.
+    * `[!CAUTION]` Negative potential consequences of an action.
+    * `[!WARNING]` Dangerous certain consequences of an action.
+
+## Links
+
+* Links to other documentation articles should be relative, not absolute. Include the `.md` suffix.
+* Links to bookmarks within the same article should be relative and start with `#`.
+* Link descriptions should be descriptive and make sense on their own. Don't use "click here" or "this link" or "here".
+
+## Images
+
+* Use images only when they add value.
+* Images have a descriptive and meaningful alt text that starts with "Screenshot showing" and ends with ".".
+* Videos have a descriptive and meaningful alt text or title that starts with "Video showing" and ends with ".".
+
+## Numbered steps
+
+* Write complete sentences with capitalization and periods
+* Use imperative verbs
+* Clearly indicate where actions take place (UI location)
+* For single steps, use a bullet instead of a number
+* When allowed, use angle brackets for menu sequences (File > Open)
+* When writing ordered lists, only use 1's.
+
+## Terminology
+
+* Use "Select" instead of "Click" for UI elements like buttons, menu items, links, dropdowns, and checkboxes.
+* Use "might" instead of "may" for conditional statements.
+* Avoid latin abbreviations like "e.g.". Use "for example" instead.
+* Use the verb "to enable" instead "to allow" unless you're referring to permissions.
+* Follow the terms and capitalization guidelines in #fetch [VS Code docs wiki](https://github.com/microsoft/vscode-docs/wiki/VS-Code-glossary)
+
+
+## Complete style guide
+
+Find all the details of the style guide in these files:
+
+- `./content/contribute/style/grammar.md` – Grammar rules
+- `./content/contribute/style/formatting.md` – Formatting rules
+- `./content/contribute/style/recommended-words.md` – Approved words and phrasing
+- `./content/contribute/style/voice-tone.md` – Voice and tone guidance

.github/prompts/freshness-tier1.prompt.md

@@ -0,0 +1,16 @@
+---
+mode: 'edit'
+---
+
+Imagine you're an experienced technical writer. You need to review content for
+how fresh and up to date it is. Apply the following:
+
+1. Fix spelling errors and typos
+2. Verify whether the markdown structure conforms to common markdown standards
+3. Ensure the content follows our [style guide file](../instructions/styleguide-instructions.md) as a guide.
+4. Make sure the titles on the page provide better context about the content (for an improved search experience).
+5. Ensure all the components formatted correctly.
+6. Improve the SEO keywords.
+7. If you find numbered lists, make sure their numbering only uses 1's.
+
+Do your best and don't be lazy.

.github/prompts/freshness-tier2.prompt.md

@@ -0,0 +1,22 @@
+---
+mode: 'edit'
+---
+
+Imagine you're an experienced technical writer. You need to review content for
+how fresh and up to date it is. Apply the following:
+
+1. Improve the presentational layer - components, splitting up the page into smaller pages
+   Consider the following:
+
+    1. Can you use tabs to display multiple variants of the same steps?
+    2. Can you make a key item of information stand out with a call-out?
+    3. Can you reduce a large amount of text to a series of bullet points?
+    4. Are there other code components you could use?
+2. Check if any operating systems or package versions mentioned are still current and supported
+3. Check the accuracy of the content
+4. If appropriate, follow the document from start to finish to see if steps make sense in sequence
+5. Try to add some helpful next steps to the end of the document, but only if there are no *Next steps* or *Related pages* section, already.
+6. Try to clarify, shorten or improve the efficiency of some sentences.
+7. Check for LLM readibility.
+
+Do your best and don't be lazy.

.github/prompts/review.prompt.md

@@ -0,0 +1,7 @@
+---
+mode: edit
+description: You are a technical writer reviewing an article for clarity, conciseness, and adherence to the documentation writing style guidelines.
+---
+Review the article for clarity, conciseness, and adherence to our documentation [style guidelines](../instructions/styleguide-instructions.md).
+
+Provide concrete and practical suggestions for improvement.

content/get-started/docker-overview.md

@@ -17,21 +17,20 @@ aliases:
 ---
 
 Docker is an open platform for developing, shipping, and running applications.
-Docker enables you to separate your applications from your infrastructure so
-you can deliver software quickly. With Docker, you can manage your infrastructure
-in the same ways you manage your applications. By taking advantage of Docker's
-methodologies for shipping, testing, and deploying code, you can
-significantly reduce the delay between writing code and running it in production.
+Docker separates your applications from your infrastructure, enabling faster
+software delivery. With Docker, you manage your infrastructure the same way you
+manage your applications. By using Docker's methodologies for shipping, testing,
+and deploying code, you can significantly reduce the time between writing code
+and running it in production.
 
 ## The Docker platform
 
-Docker provides the ability to package and run an application in a loosely isolated
-environment called a container. The isolation and security lets you run many
-containers simultaneously on a given host. Containers are lightweight and contain
-everything needed to run the application, so you don't need to rely on what's
-installed on the host. You can share containers while you work,
-and be sure that everyone you share with gets the same container that works in the
-same way.
+Docker packages and runs applications in loosely isolated environments called
+containers. This isolation and security allows you to run many containers
+simultaneously on a single host. Containers are lightweight and contain
+everything needed to run the application, eliminating dependencies on the host
+system. When you share containers, everyone gets the same container that works
+identically.
 
 Docker provides tooling and a platform to manage the lifecycle of your containers:
 
@@ -47,48 +46,44 @@ Docker provides tooling and a platform to manage the lifecycle of your container
 ### Fast, consistent delivery of your applications
 
 Docker streamlines the development lifecycle by allowing developers to work in
-standardized environments using local containers which provide your applications
-and services. Containers are great for continuous integration and continuous
+standardized environments using local containers that provide your applications
+and services. Containers are ideal for continuous integration and continuous
 delivery (CI/CD) workflows.
 
 Consider the following example scenario:
 
-- Your developers write code locally and share their work with their colleagues
-  using Docker containers.
-- They use Docker to push their applications into a test environment and run
-  automated and manual tests.
-- When developers find bugs, they can fix them in the development environment
-  and redeploy them to the test environment for testing and validation.
-- When testing is complete, getting the fix to the customer is as simple as
-  pushing the updated image to the production environment.
+- Developers write code locally and share their work with colleagues using Docker containers.
+- They use Docker to push their applications into a test environment and run automated and manual tests.
+- When developers find bugs, they can fix them in the development environment and redeploy them to the test environment for testing and validation.
+- When testing is complete, getting the fix to the customer is as simple as pushing the updated image to the production environment.
 
 ### Responsive deployment and scaling
 
-Docker's container-based platform allows for highly portable workloads. Docker
+Docker's container-based platform enables highly portable workloads. Docker
 containers can run on a developer's local laptop, on physical or virtual
 machines in a data center, on cloud providers, or in a mixture of environments.
 
 Docker's portability and lightweight nature also make it easy to dynamically
 manage workloads, scaling up or tearing down applications and services as
-business needs dictate, in near real time.
+business needs dictate, in near real-time.
 
 ### Running more workloads on the same hardware
 
 Docker is lightweight and fast. It provides a viable, cost-effective alternative
-to hypervisor-based virtual machines, so you can use more of your server
-capacity to achieve your business goals. Docker is perfect for high density
+to hypervisor-based virtual machines, allowing you to use more of your server
+capacity to achieve your business goals. Docker is perfect for high-density
 environments and for small and medium deployments where you need to do more with
 fewer resources.
 
 ## Docker architecture
 
 Docker uses a client-server architecture. The Docker client talks to the
-Docker daemon, which does the heavy lifting of building, running, and
+Docker daemon, which handles the heavy lifting of building, running, and
 distributing your Docker containers. The Docker client and daemon can
 run on the same system, or you can connect a Docker client to a remote Docker
 daemon. The Docker client and daemon communicate using a REST API, over UNIX
 sockets or a network interface. Another Docker client is Docker Compose,
-that lets you work with applications consisting of a set of containers.
+which lets you work with applications consisting of a set of containers.
 
 ![Docker Architecture diagram](images/docker-architecture.webp)
 
@@ -107,36 +102,36 @@ Docker API. The Docker client can communicate with more than one daemon.
 
 ### Docker Desktop
 
-Docker Desktop is an easy-to-install application for your Mac, Windows or Linux environment that enables you to build and share containerized applications and microservices. Docker Desktop includes the Docker daemon (`dockerd`), the Docker client (`docker`), Docker Compose, Docker Content Trust, Kubernetes, and Credential Helper. For more information, see [Docker Desktop](/manuals/desktop/_index.md).
+Docker Desktop is an easy-to-install application for your Mac, Windows, or Linux environment that enables you to build and share containerized applications and microservices. Docker Desktop includes the Docker daemon (`dockerd`), the Docker client (`docker`), Docker Compose, Docker Content Trust, Kubernetes, and Credential Helper. For more information, see [Docker Desktop](/manuals/desktop/_index.md).
 
 ### Docker registries
 
 A Docker registry stores Docker images. Docker Hub is a public
 registry that anyone can use, and Docker looks for images on
-Docker Hub by default. You can even run your own private registry.
+Docker Hub by default. You can also run your own private registry.
 
 When you use the `docker pull` or `docker run` commands, Docker pulls the required images from your configured registry. When you use the `docker push` command, Docker pushes
 your image to your configured registry.
 
 ### Docker objects
 
-When you use Docker, you are creating and using images, containers, networks,
-volumes, plugins, and other objects. This section is a brief overview of some
+When you use Docker, you create and use images, containers, networks,
+volumes, plugins, and other objects. This section provides a brief overview of some
 of those objects.
 
 #### Images
 
 An image is a read-only template with instructions for creating a Docker
 container. Often, an image is based on another image, with some additional
-customization. For example, you may build an image which is based on the `ubuntu`
+customization. For example, you may build an image that is based on the `ubuntu`
 image, but installs the Apache web server and your application, as well as the
 configuration details needed to make your application run.
 
 You might create your own images or you might only use those created by others
 and published in a registry. To build your own image, you create a Dockerfile
 with a simple syntax for defining the steps needed to create the image and run
 it. Each instruction in a Dockerfile creates a layer in the image. When you
-change the Dockerfile and rebuild the image, only those layers which have
+change the Dockerfile and rebuild the image, only those layers that have
 changed are rebuilt. This is part of what makes images so lightweight, small,
 and fast, when compared to other virtualization technologies.
 
@@ -168,28 +163,28 @@ $ docker run -i -t ubuntu /bin/bash
 When you run this command, the following happens (assuming you are using
 the default registry configuration):
 
-1.  If you don't have the `ubuntu` image locally, Docker pulls it from your
-    configured registry, as though you had run `docker pull ubuntu` manually.
+1. If you don't have the `ubuntu` image locally, Docker pulls it from your
+   configured registry, as though you had run `docker pull ubuntu` manually.
 
-2.  Docker creates a new container, as though you had run a `docker container create`
-    command manually.
+2. Docker creates a new container, as though you had run a `docker container create`
+   command manually.
 
-3.  Docker allocates a read-write filesystem to the container, as its final
-    layer. This allows a running container to create or modify files and
-    directories in its local filesystem.
+3. Docker allocates a read-write filesystem to the container, as its final
+   layer. This allows a running container to create or modify files and
+   directories in its local filesystem.
 
-4.  Docker creates a network interface to connect the container to the default
-    network, since you didn't specify any networking options. This includes
-    assigning an IP address to the container. By default, containers can
-    connect to external networks using the host machine's network connection.
+4. Docker creates a network interface to connect the container to the default
+   network, since you didn't specify any networking options. This includes
+   assigning an IP address to the container. By default, containers can
+   connect to external networks using the host machine's network connection.
 
-5.  Docker starts the container and executes `/bin/bash`. Because the container
-    is running interactively and attached to your terminal (due to the `-i` and `-t`
-    flags), you can provide input using your keyboard while Docker logs the output to
-    your terminal.
+5. Docker starts the container and executes `/bin/bash`. Because the container
+   is running interactively and attached to your terminal (due to the `-i` and `-t`
+   flags), you can provide input using your keyboard while Docker logs the output to
+   your terminal.
 
-6.  When you run `exit` to terminate the `/bin/bash` command, the container
-    stops but isn't removed. You can start it again or remove it.
+6. When you run `exit` to terminate the `/bin/bash` command, the container
+   stops but isn't removed. You can start it again or remove it.
 
 ## The underlying technology
 
@@ -204,5 +199,7 @@ in a separate namespace and its access is limited to that namespace.
 
 ## Next steps
 
+Ready to start using Docker? Here's what to do next:
+
 - [Install Docker](/get-started/get-docker.md)
 - [Get started with Docker](/get-started/introduction/_index.md)

content/get-started/get-docker.md

@@ -14,22 +14,22 @@ aliases:
 
 Docker is an open platform for developing, shipping, and running applications.
 
-Docker allows you to separate your applications from your infrastructure so you
-can deliver software quickly. With Docker, you can manage your infrastructure in
-the same ways you manage your applications. 
+Docker lets you separate your applications from your infrastructure, so you can deliver software quickly. You can manage your infrastructure the same way you manage your applications.
 
-By taking advantage of Docker’s
-methodologies for shipping, testing, and deploying code quickly, you can
-significantly reduce the delay between writing code and running it in production.
+By using Docker’s methodologies for shipping, testing, and deploying code, you can significantly reduce the time between writing code and running it in production.
 
-You can download and install Docker on multiple platforms. Refer to the following
-section and choose the best installation path for you.
+You can download and install Docker on multiple platforms:
 
+- **macOS**
+- **Windows**
+- **Linux**
+
+Refer to the following section and choose the best installation path for your operating system.
+
+> [!IMPORTANT]
 > **Docker Desktop terms**
 >
-> Commercial use of Docker Desktop in larger enterprises (more than 250
-> employees OR more than $10 million USD in annual revenue) requires a [paid
-> subscription](https://www.docker.com/pricing/).
+> Commercial use of Docker Desktop in larger enterprises (more than 250 employees OR more than $10 million USD in annual revenue) requires a [paid subscription](https://www.docker.com/pricing/).
 
 <div class="not-prose">
 {{< card
@@ -52,5 +52,5 @@ section and choose the best installation path for you.
 </div>
 
 > [!NOTE]
->
+> If you're looking for information on how to install Docker Engine, see [Docker Engine installation overview](/engine/install/).
 > If you're looking for information on how to install Docker Engine, see [Docker Engine installation overview](/engine/install/).