docs: improve Quick Start and Running Locally

- use a warning box for nicer looking formatting than unicode

- clarify that dev container does not necessarily need VSCode given that there is a CLI
  - it said this before, but the ordering of the wording made it confusing and easy to miss
  - also use code backticks for `devcontainer` CLI as that is the name of the command (see k8s style guide: https://kubernetes.io/docs/contribute/style/style-guide/#code-style-inline-code)
    - use "Dev Container" as the proper noun when referring to the tool in general (not specific to CLI)
- use `argo-workflows` consistently when describing the folder name (which is by default the name of the repo)

- move "Git Clone" section into Requirements
  - this is not needed when using the Dev Container, as it is mounted to the correct directory inside the container

- remove copy+pasted descriptions of what a Dev Container is
  - Dev Container docs say this verbatim: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers. leave that to their docs to describe it if people are unfamiliar with the tool

- use present tense where possible / appropriate (https://kubernetes.io/docs/contribute/style/style-guide/#use-present-tense)
  - "will run" -> "runs"
  - "you'll have" -> "you have"
- use more direct language where possible (https://kubernetes.io/docs/contribute/style/style-guide/#use-simple-and-direct-language)
  - "a cluster to use to test against" -> "a cluster to test against"

- fix miscellaneous grammar
  - run-on sentences, missing commas, extra commas, etc

Signed-off-by: Anton Gilgur <agilgur5@gmail.com>

docs/quick-start.md

@@ -11,7 +11,8 @@ Before you start you need a Kubernetes cluster and `kubectl` set up to be able t
 
 Alternatively, if you want to try out Argo Workflows and don't want to set up a Kubernetes cluster, try the [Killercoda course](training.md#hands-on).
 
-⚠️ These instructions are intended to help you get started quickly. They are not suitable in production. For production installs, please refer to [the installation documentation](installation.md) ⚠️
+!!! Warning "Development vs. Production"
+    These instructions are intended to help you get started quickly. They are not suitable in production. For production installs, please refer to [the installation documentation](installation.md).
 
 ## Install Argo Workflows
 

docs/running-locally.md

@@ -2,22 +2,17 @@
 
 You have two options:
 
-1. If you're using VSCode, you use the [Dev-Container](#development-container). This takes about 7 minutes. This can also be used from the dev-container CLI.
+1. Use the [Dev Container](#development-container). This takes about 7 minutes. This can be used with VSCode or with the `devcontainer` CLI.
 1. Install the [requirements](#requirements) on your computer manually. This takes about 1 hour.
 
-## Git Clone
-
-Clone the Git repo into: `$GOPATH/src/github.com/argoproj/argo-workflows`. Any other path will mean the code
-generation does not work.
-
 ## Development Container
 
-A development container is a running Docker container with a well-defined tool/runtime stack and its prerequisites. It should be able to do everything you need to do to develop argo workflows using the development container without installing tools on your local machine. It takes quite a long time to build the container. It will run k3d inside the container so you'll have a cluster to use to test against. To communicate with services running either in other development containers or directly on the local developer machine (e.g., a database) the following URL can be used in the workflow spec: `host.docker.internal:<PORT>`. This facilitates the implementation of workflows, which need to connect to a database or an API server.
+The development container should be able to do everything you need to do to develop Argo Workflows without installing tools on your local machine. It takes quite a long time to build the container. It runs `k3d` inside the container so you have a cluster to test against. To communicate with services running either in other development containers or directly on the local machine (e.g. a database), the following URL can be used in the workflow spec: `host.docker.internal:<PORT>`. This facilitates the implementation of workflows which need to connect to a database or an API server.
 
 You can use the development container in a few different ways:
 
-1. [Visual Studio Code](https://code.visualstudio.com/) with [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension lets you use a Docker container as a full-featured development environment. Open the clone of argo-workflows folder in VS code and it should offer to use the development container automatically. System requirements can be found [here](https://code.visualstudio.com/docs/remote/containers#_system-requirements). Visual Studio will allow you to forward ports to allow your external browser to access the running components.
-1. [Dev-container CLI](https://github.com/devcontainers/cli). Install the tool and from the argo-workflow folder do `devcontainer up --workspace-folder .` followed by `devcontainer exec --workspace-folder . /bin/bash` to get a shell where you can start building the code. You can use your choice editor outside the docker image to edit code, the changes are mirrored inside the container. Due to a limitation in the CLI only port 8080 (the Web UI) will get exposed for you to access if you run this way. Other services are usable from the shell inside.
+1. [Visual Studio Code](https://code.visualstudio.com/) with [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers). Open your `argo-workflows` folder in VSCode and it should offer to use the development container automatically. VSCode will allow you to forward ports to allow your external browser to access the running components.
+1. [`devcontainer` CLI](https://github.com/devcontainers/cli). Once installed, go to your `argo-workflows` folder and run `devcontainer up --workspace-folder .` followed by `devcontainer exec --workspace-folder . /bin/bash` to get a shell where you can build the code. You can use any editor outside the container to edit code; any changes will be mirrored inside the container. Due to a limitation of the CLI, only port 8080 (the Web UI) will be exposed for you to access if you run this way. Other services are usable from the shell inside.
 
 Once you have entered the container, continue to [Developing Locally](#developing-locally).
 
@@ -43,6 +38,8 @@ Note:
 
 ## Requirements
 
+Clone the Git repo into: `$GOPATH/src/github.com/argoproj/argo-workflows`. Any other path will break the code generation.
+
 Add the following to your `/etc/hosts`:
 
 ```text
@@ -53,7 +50,7 @@ Add the following to your `/etc/hosts`:
 127.0.0.1 azurite
 ```
 
-To build on your own machine without using the dev-container you will need
+To build on your own machine without using the Dev Container you will need:
 
 * [Go](https://golang.org/dl/)
 * [Yarn](https://classic.yarnpkg.com/en/docs/install/#mac-stable)
@@ -73,15 +70,15 @@ Alternatively, you can use [Minikube](https://github.com/kubernetes/minikube) to
 Once a local Kubernetes cluster has started via `minikube start`, your kube config will use Minikube's context
 automatically.
 
-⚠️ Do not use Docker for Desktop with its embedded Kubernetes, it does not support Kubernetes RBAC (i.e. `kubectl auth can-i` always
-returns `allowed`).
+!!! Warning
+    Do not use Docker Desktop's embedded Kubernetes, it does not support Kubernetes RBAC (i.e. `kubectl auth can-i` always returns `allowed`).
 
 ## Developing locally
 
 To start:
 
 * The controller, so you can run workflows.
-* MinIO (<http://localhost:9000>, use admin/password) so you can use artifacts:
+* MinIO (<http://localhost:9000>, use admin/password) so you can use artifacts.
 
 Run: