Merge branch 'edge' into aacrawfi/remove-quickstarts

.github/config/en-custom.txt

@@ -426,8 +426,25 @@ vHost
 URI
 uri
 rabbitMQ
+linenos
+linenostart
+markdownConfig
+hl
 azureCache
 listKeys
 primaryKey
 quickstart
 quickstarts
+mygroup
+Kubeconfig
+unregister
+Unregisters
+br
+myregistry
+GCP
+Fargate
+untyped
+authSource
+mongodb
+MYCONNECTION
+VHOST

.github/workflows/website.yaml

@@ -21,6 +21,7 @@ jobs:
       GOVER: '^1.17'
       TUTORIAL_PATH: './docs/content/user-guides/tutorials/'
       CODE_ZIP_PATH: './docs/static/tutorial/'
+      HUGO_VERSION: 0.117.0
       HUGO_ENV: production
       SWA_BASE: 'wonderful-plant-020417a1e'
     steps:
@@ -48,7 +49,7 @@ jobs:
       - name: Setup Hugo
         uses: peaceiris/[email protected]
         with:
-          hugo-version: 0.102.3
+          hugo-version: ${{ env.HUGO_VERSION }}
           extended: true
       - name: Setup Docsy
         run: |

.gitignore

@@ -1,4 +1,3 @@
-docs/content/reference/cli/rad*
 docs/public
 docs/.hugo_build.lock
 dictionary.dic

docs/content/author-apps/application/index.md

@@ -12,6 +12,12 @@ tags: ["applications"]
 
 An [application]({{< ref application-graph>}}) is the primary resource that contains all of your services and relationships.
 
+Because Radius has all the relationships and requirements of an application, deployments and configurations are simplified. Developers no longer need to specify all the identity, networking, or other configuration that is normally required, and operators don't need to write custom deployment scripts.
+
+For example, if you want a container to read from an Azure Storage Account without using Radius, this normally requires creating managed identities, RBAC roles, identity federation, Kubernetes service accounts, and more. With Radius, developers can define a single [connection]({{< ref "container#connections" >}}) from their container to a Storage Account, and Radius sets up all the required configuration automatically.
+
+<img src="graph-automation.png" alt="A diagram showing a connection from a Radius container to an Azure storage account resulting in managed identities, role-based access control, and CSI drivers." width=600px >
+
 ## Extensions
 
 Extensions allow you to customize how resources are generated or customized as part of deployment.

docs/content/author-apps/container/container-overview.md

@@ -70,9 +70,22 @@ Refer to the probes section of the [container resource schema]({{< ref "containe
 
 ### Connections
 
-Connections enable communication between your container and other resources, such as databases, message queues, and other services. A connection injects information about the resource you connect to as environment variables. This could be connection strings, access keys, password or other information needed for communication between the container and the resource it connects to. It also enables you to configure the RBAC permissions for the container to access the resource.
+When a connection between two resources is declared, Radius injects resource related information into environment variables that are then used to access the respective resource without having to hard code URIs, connection strings, access keys, or anything that application code needs to successfully communicate.
 
-Refer to the [connections schema] for containers({{< ref "container-schema#connections" >}}) for more details.
+These environment variables follow a naming convention that makes their use predictable. The naming pattern is derived from the connection name and resource type, which determines what values are required. This way the code that needs to read the values gets to define how they are named. Refer to the [reference documentation]({{< ref resource-schema >}}) of each resource for more information. 
+
+For example, adding a connection called `myconnection` that connects to a MongoDB resource would result in the following environment variables being injected:
+
+```sh
+# the connection string to the resource
+CONNECTION_MYCONNECTION_CONNECTIONSTRING="mongodb://mongo:27017/mongo?authSource=admin"
+# Database name of the target resource
+CONNECTION_MYCONNECTION_DATABASE="my-database"
+# Username of the target resource
+CONNECTION_MYCONNECTION_USERNAME="admin"
+```
+
+Alternatively, if you already have another convention you would like to follow or if you just prefer to be explicit, you may ignore the values generated by a connection and instead override it by setting your own environment variable values. Refer to the [environment variables quickstart]({{< ref quickstart-environment-variables >}}) for more details.
 
 ### Extensions
 

docs/content/author-apps/container/howto-keyvault-volume/index.md

@@ -26,10 +26,10 @@ This how-to guide will provide an overview of how to:
 
 ## Step 1: Initialize Radius 
 
-Begin by running `rad init`. Make sure to configure an Azure cloud provider:
+Begin by running [`rad init --full`]({{< ref rad_init >}}). Make sure to configure an Azure cloud provider:
 
 ```bash
-rad init
+rad init --full
 ```
 
 ## Step 2: Define a Radius environment

docs/content/author-apps/platform-resources/howto-aws-resources/_index.md

@@ -36,10 +36,10 @@ eksctl create cluster --name <my-cluster> --region=<my-region>
 
 Create a [Radius environment]({{< ref "/operations/environments" >}}) where you will deploy your application.
 
-Use the `rad init` command to initialize a new environment into your current kubectl context:
+Run [`rad init --full`]({{< ref rad_init >}}) to initialize a new environment into your current kubectl context:
 
 ```bash
-rad init
+rad init --full
 ```
 
 Follow the prompts to install the [control plane services]({{< ref architecture-concept >}}), create an [environment resource]({{< ref "operations/environments" >}}), and create a [local workspace]({{< ref workspaces >}}). You will be asked for:

docs/content/author-apps/platform-resources/howto-azure-resources/index.md

@@ -25,10 +25,10 @@ The steps below will showcase a "rad-ified" version of the existing [Azure AD wo
 
 ## Step 1: Initialize Radius 
 
-Begin by running `rad init`. Make sure to configure an Azure cloud provider:
+Begin by running [`rad init --full`]({{< ref rad_init >}}). Make sure to configure an Azure cloud provider:
 
 ```bash
-rad init
+rad init --full
 ```
 
 ## Step 2: Define a Radius environment 

docs/content/concepts/application-graph/index.md

@@ -14,18 +14,10 @@ Radius offers an [application resource]({{< ref "/author-apps/application" >}})
 
 ## Graphs are better than lists
 
-Within an application deployed with Radius, developers can express both the resources (_containers, databases, message queues, etc._), as well as all the relationships between them. This forms the Radius application graph. This graph is powerful because it allows Radius to understand the relationships between resources, and automate the deployment and configuration of your application. Plus, it allows you to visualize your application in a way that is more intuitive than a list of resources.
+Within an application deployed with Radius, developers can express both the resources (_containers, databases, message queues, etc._), as well as all the relationships between them. This forms the Radius application graph. This graph is powerful because it allows Radius to understand the relationships between resources, simplifying the [deployment]({{< ref "deploy-applications" >}}) and [configuration]({{< ref "application" >}}) of your application. Plus, it allows you to visualize your application in a way that is more intuitive than a list of resources.
 
 <img src="list-to-graph.png" alt="A diagram showing the move from a set of infrastructure lists to a graph of resources" width=600px >
 
-## Automate your application deployment
-
-Because Radius now has all the relationships and requirements of an application, it can be deployed and configured automatically. Developers no longer need to specify all the identity, networking, or other configuration that is normally required, and operators don’t need to write custom deployment scripts.
-
-For example, if you want a container to read from an Azure Storage Account without using Radius, this normally requires creating managed identities, RBAC roles, identity federation, Kubernetes service accounts, and more. With Radius, developers can define a single connection from their container to a Storage Account, and Radius sets up all the required configuration automatically.
-
-<img src="graph-automation.png" alt="A diagram showing a connection from a Radius container to an Azure storage account resulting in managed identities, role-based access control, and CSI drivers." width=600px >
-
 ## Self-documenting applications
 
 The Radius application graph also allows your application to be self-documenting, where developers and operators can query and reason about the same application definition. Instead of multiple views of logs, infrastructure, and code, Radius provides a single source of truth for your application.

docs/content/contributing/contributing-docs.md → docs/content/contributing/contributing-docs/index.md

@@ -9,11 +9,17 @@ slug: "docs"
 
 The Radius docs are built on [Hugo](https://gohugo.io) with the [Docsy](https://docsy.dev) theme. GitHub Actions are used to build and deploy the docs upon each PR.
 
-## Docs environment
+Radius uses the [Diátaxis framework](https://diataxis.fr/) for its documentation:
 
-### GitHub Codespace
+<img src="diataxis.png" alt="Diagram showing the diataxis framework" width=800px >
 
-Get up and running with a GitHub Codespace in seconds. This will give you a fully configured environment with all the tools you need to build the docs.
+Follow the guidance on this page to learn how to get started, how to contribute, and how to use the Diátaxis framework to create new docs.
+
+## Setup your docs environment
+
+### GitHub Codespace (easiest)
+
+It's easy to get up and running with a GitHub Codespace. This will give you a fully configured environment with all the tools you need to build the docs, all in your browser.
 
 {{< button link="https://github.com/codespaces/new?hide_repo_select=true&repo=421982809" text="Create codespace" >}}
 
@@ -46,29 +52,25 @@ Get up and running with a GitHub Codespace in seconds. This will give you a full
 3. Generate CLI docs:
 
    ```sh
-   cd radius
+   pushd radius
    go run ./cmd/docgen/main.go ../docs/docs/content/reference/cli
+   popd
    ```
 
-4. Change to docs directory:
-
-   ```sh
-   cd ../docs/docs
-   ```
-
-5. Update submodules:
+4. Update submodules:
 
    ```sh
+   cd docs
    git submodule update --init --recursive
    ```
 
-6. Install npm packages:
+5. Install npm packages:
 
    ```sh
    npm install
    ```
 
-7. Initialize the docsy theme:
+6. Initialize the docsy theme:
 
    ```sh
    cd themes/docsy
@@ -87,75 +89,76 @@ Get up and running with a GitHub Codespace in seconds. This will give you a full
 
 3. Navigate to `http://localhost:1313/`
 
-## Style and tone
+## Types of docs
 
-These conventions should be followed throughout all Radius documentation to ensure a consistent experience across all docs.
+There are 5 types of docs in Radius:
 
-| Style/Tone | Guidance |
-|---------|-------------|
-|**Casing**|Use upper case only:<ul><li>At the start of a sentence or header</li><li>For proper nouns including names of technologies (Redis, Kubernetes, etc.)</li> <li>Names of Radius concepts (Radius Recipe, Radius Environment, Radius Application, etc.)</li></ul>|
-|**Headers and titles**|Headers and titles must be descriptive and clear, use sentence casing i.e. use the above casing guidance for headers and titles too| 
-|**Use simple sentences**|Easy-to-read sentences mean the reader can quickly use the guidance you share.| 
-|**Avoid the first person**|Use second person "you", "your" instead of "I", "we", "our".| 
-|**Assume a new developer audience**|Some obvious steps can seem hard. E.g. Now set an environment variable Radius to a value X. It is better to give the reader the explicit command to do this, rather than having them figure this out.| 
-|**Use present tense**|Avoid sentences like "this command will install redis", which implies the action is in the future. Instead, use "This command installs redis" which is in the present tense. |
-
-## Spelling
-
-The docs pipeline uses [aspell](http://aspell.net/) to check for spelling mistakes. If you need to add a new custom word to the allow-list, update `.github/config/en-custom.txt`.
+1. **Concept** - A concept doc is a high-level overview of the project or an area of the project.
+2. **Overview** - A overview page documents a specific feature or capability of the project, with information on what the feature is and additional context and links on how to use it.
+3. **How-To** - A how-to guide is a step-by-step guide to help the reader achieve a specific task. It assumes the reader has a basic understanding of the project and its concepts. For more information on how-to guides, see [Diátaxis](https://diataxis.fr/how-to-guides/).
+4. **Reference** - A reference doc is a detailed description of a specific feature or capability of the project. It assumes the reader has a basic understanding of the project and its concepts. For more information on reference docs, see [Diátaxis](https://diataxis.fr/reference/).
 
-## Contributing a new docs page
+Overall:
 
-- Make sure the documentation you are writing is in the correct place in the hierarchy.
 - Avoid creating new sections where possible, there is a good chance a proper place in the docs hierarchy already exists.
 - Make sure to include a complete [Hugo front-matter](#front-matter).
-- Determine the category or the type of doc you are contributing.
-   - **Concept** - A concept doc is a high-level overview of the project or an area of the project.
-   - **Overview** - A overview page documents a specific feature or capability of the project, with information on what the feature is and additional context and links on how to use it.
-   - **Reference app** - A reference app-doc is for running an application sample or an example of using the project or a particular feature.
-   - **How-To** - A how-to guide is an elaborate step-by-step guide to help the reader achieve a specific goal. It should provide the reader with an in-depth understanding of what the feature does.
+- Determine the [type of doc](#types-of-docs) you are contributing
 
-### Contributing a new Concept doc
+### Concept docs
+
+Visit [Diátaxis](https://diataxis.fr/explanation/) for more information on explanatory documentation that helps the user understand the project or a specific area of the project.
 
-- Ensure the doc is in the correct place in the hierarchy.
 - Ensure the reader can understand why they should care about the project or the concept. What problems does it help them solve?
 - Provide a link to the overview page of the feature that justifies the concept(s)
-- Also provide the reader with related links if needed (this can be other how-to guides, samples for reference)
+- Provide the reader with related links if needed (this can be other concepts, overviews, how-to guides, or references)
 - Set the `category` as `Concept` in [Hugo front-matter](#front-matter).
 
-### Contributing a new Overview doc
+### Overview docs
+
+Visit [Diátaxis](https://diataxis.fr/explanation/) for more information on explanatory documentation that helps the user understand the project or a specific area of the project.
 
-- Ensure the doc is in the correct place in the hierarchy.
 - Ensure the reader can understand why they should care about the feature and what it enables them to do. 
 - If applicable, ensure the doc references the reference spec document.
 - If applicable, ensure the doc is consistent with any related concepts or specs in terms of names, parameters, and terminology. Update both the concept, spec, and the doc as needed. Avoid repeating the spec. The idea is to give the reader more information and background on the capability so that they can try this out. 
-- Provide a link to the spec in the [Reference]({{<ref reference >}}) section and provide the reader with related links (this can be other how-to guides, samples for reference )
+- Provide the reader with related links if needed (this can be other concepts, overviews, how-to guides, or references)
 - Set the `category` as `Overview` in [Hugo front-matter](#front-matter).
 
-### Contributing a new How-To guide
+### How-To guides
 
-- Sub directory naming - the directory name should be descriptive and if referring to a specific component or concept should begin with the relevant name. Example *pubsub-namespaces*.
+Visit [Diátaxis](https://diataxis.fr/how-to-guides/) for more information on how-to documentation that helps the user accomplish a specific task.
 - Do not assume the reader is using a specific environment unless the article itself is specific to an environment. This includes OS (Windows/Linux/MacOS), deployment target (Kubernetes, IoT, etc.), or programming language. If instructions vary between operating systems, provide guidance for all.
 - Include code/sample/config snippets that can be easily copied and pasted.
-- At the end of the article, provide the reader with related links and next steps (this can be other relevant "how-to", samples for reference or related concepts).
+- Provide the reader with related links if needed (this can be other concepts, overviews, how-to guides, or references)
 - Set the `category` as `How To` in [Hugo front-matter](#front-matter).
 
-### Contributing a new Reference application
+### Reference docs
 
-- Ensure the doc has enough instructions to run the sample
-- Add the architecture diagram of the application sample if possible 
-- Make sure the sample code is added to [radius samples](https://github.com/project-radius/samples)
-- Set the `category` as `Reference app` in [Hugo front-matter](#front-matter).
+Visit [Diátaxis](https://diataxis.fr/reference/) for more information on reference documentation that helps the user understand the details of a specific feature or capability of the project.
 
-## Requirements for radius.dev
+Reference docs should be auto-generated from source-code whenever possible. Please contact the maintainers if you need to add a new reference doc, or open an Issue to discuss.
 
-Any contribution must ensure not to break the website build. The way Hugo builds the website requires following the below guidance.
+## Writing styles and tips
 
-### Files and folder names
+### Style and tone
+
+These conventions should be followed throughout all Radius documentation to ensure a consistent experience across all docs.
 
-File and folder names should be globally unique.
-    - `\service-invocation`
-    - `service-invocation-overview.md`
+| Style/Tone | Guidance |
+|---------|-------------|
+|**Casing**|Use upper case only:<ul><li>At the start of a sentence or header</li><li>For proper nouns including names of technologies (Redis, Kubernetes, etc.)</li> <li>Names of Radius concepts (Radius Recipe, Radius Environment, Radius Application, etc.)</li></ul>|
+|**Headers and titles**|Headers and titles must be descriptive and clear, use sentence casing i.e. use the above casing guidance for headers and titles too| 
+|**Use simple sentences**|Easy-to-read sentences mean the reader can quickly use the guidance you share.| 
+|**Avoid the first person**|Use second person "you", "your" instead of "I", "we", "our".| 
+|**Assume a new developer audience**|Some obvious steps can seem hard. E.g. Now set an environment variable Radius to a value X. It is better to give the reader the explicit command to do this, rather than having them figure this out.| 
+|**Use present tense**|Avoid sentences like "this command will install redis", which implies the action is in the future. Instead, use "This command installs redis" which is in the present tense. |
+
+### Spelling
+
+The docs pipeline uses [aspell](http://aspell.net/) to check for spelling mistakes. If you need to add a new custom word to the allow-list, update `.github/config/en-custom.txt`.
+
+## Tips and tricks
+
+Any contribution must ensure not to break the website build. The way Hugo builds the website requires following the below guidance.
 
 ### Front-matter