restructure, proof read

pages/adding-new-application/background-app-install.md

@@ -2,15 +2,16 @@
 title: Background on Application Installation
 description: >-
   In this guide we will lay out how your user provided values tie in with the deployment process as it relates to the configuration and templating of the app.
+  A good unerstanding of an app's journey into your cluster will go a long way if you want to contribute your own application to the marketplace.
 ---
 
 When a user sets up a new Plural workspace in a git repository (we'll call that a *deployment repository* going forward) a `workspace.yaml` file is created that stores global values for that cluster such as the cloud account and region, the cluster and VPC name and what subdomain all the applications will be hosted under.
 Next, the user can install an application bundle using the `plural bundle install <app_name> <bundle>` CLI command.
-> Most applications come with more than bundle, one for each targeted cloud provider.
+> Most applications come with more than one bundle, one for each targeted cloud provider.
 The CLI will then prompt the user for for inputs needed to setup that application, along with any dependencies of the application.
 These inputs are saved in the `context.yaml` file.
 
-For example, the `tree` of a deployment repository, where we installed Dagster with `plural bundle install dagster dagster-aws` (among others),  might look like this:
+For example, let's have a look how the `tree` of a deployment repository, where we installed Dagster with `plural bundle install dagster dagster-aws` (among others), might look like:
 
 ```console
 $ pwd
@@ -27,7 +28,7 @@ $ tree -L 1 .
 └── context.yaml
 ```
 
-The `workspace.yaml` might look like this:
+The `workspace.yaml` would look like this:
 ```yaml
 apiVersion: plural.sh/v1alpha1
 kind: ProjectManifest
@@ -48,7 +49,7 @@ spec:
   context: {}
 ```
 
-And the `context.yaml` like this. In the `spec.configuration` section you can see the user input parametrization of each artifact.
+And the `context.yaml` like this. In the `spec.configuration` section you can see the recorded user input for each artifact.
 ```yaml
 apiVersion: plural.sh/v1alpha1
 kind: Context
@@ -88,13 +89,12 @@ spec:
       wal_bucket: pluraldev-pluraldev-postgres-wal
 ```
 
-
-Next, the user would run `plural build` or `plural build --only <app name>` which will create a wrapper Helm chart and Terraform module for that app under a dedicated directory in their deployment repository.
+Next, the user would run `plural build` or `plural build --only <app name>` which will create a wrapper Helm chart and Terraform module for that app under a dedicated directory in the deployment repository.
 The wrapper Helm chart and Terraform module depend on the application Helm chart(s) and Terraform module(s) it gets from the application's artifact repository via the Plural API.
 During this step the CLI will generate the `default-values.yaml` for the wrapper helm chart and `main.tf` for the wrapper Terraform module using its templating engine.
-More precisely, `default-values.yaml` will contain the interpolated templated values from its `values.yaml.tpl` (see below) that are derived by injecting the values saved in the `context.yaml` at `spec.configuration`.
+More precisely, `default-values.yaml` will contain the interpolated templated values from its `values.yaml.tpl` see ([Templating](/adding-new-application/templating)) that are derived by injecting the values saved in the `context.yaml` at `spec.configuration`.
 
-For example, after the `plural build --only dagster` command, the `tree` of the built Dagster application in your deployment repository might look like this:
+For example, after the `plural build --only dagster` command, the `tree` of the built Dagster application in your deployment repository would look like this:
 
 ```console
 $ pwd

pages/adding-new-application/guide.md

@@ -1,8 +1,7 @@
 ---
 title: Guide
 description: >-
-  This guide is for anyone who wants to make an open-source application available on the
-  Plural marketplace.
+  This guide is for anyone who wants to make an open-source application available on the Plural marketplace and create a new Plural artifact.
 ---
 
 To add your own application, you'll need the Helm chart for your application and corresponding Terraform.

pages/adding-new-application/application-artifact-package.md → pages/adding-new-application/plural-artifact-structure.md

@@ -1,17 +1,18 @@
 ---
-title: Plural Application Artifact Structure
+title: Plural Artifact Structure
 description: >-
   In this guide we will lay out how a Plural artifact is constructed.
 ---
 
-As mentioned in (Background on Application Installations)[/adding-new-application/background-app-install], the Plural CLI creates a wrapper Helm chart and Terraform module for each installed application and inputs the user defined values for that installation.
-Some extra configuration files are necessary in the applications artifact for Plural to be able to understand
+As mentioned in [Background on Application Installations](/adding-new-application/background-app-install),
+the Plural CLI creates a wrapper Helm chart and Terraform module for each installed application and inputs the user provided values for that installation.
+Some extra configuration files are necessary in the applications artifact for the Plural API to be able to understand:
 - the Helm charts and Terraform modules dependencies to run them through its templating engine
 - dependencies on other Plural artifacts
 - platform specific components and infrastructure configurations
 - as well as Plural's own package and version specs.
 
-As an example Dagster's artifact `tree` would look like this:
+As an example, Dagster's artifact `tree` would look like this:
 
 ```console
 $ pwd
@@ -87,9 +88,9 @@ Let's disect this artifact's structure.
 
 ## Helm
 
-The `helm` directory contains the app's Helm chart as it will be available through the Plural API and used by the Plural CLI to configure and deploy the app's Kubernetes components into your cluster.
-Many apps in Plural's marketplace define Helm charts in terms of their upstream open source versions (if they're actively maintained, allow for required customization and fit Plural's quality standards)
-as well as other helper charts, e.g. from Plural's [module-library](https://github.com/pluralsh/module-library).
+The `helm` directory contains the app's Helm chart as it will be available through the Plural API and used by the Plural CLI to configure and deploy the Kubernetes components into your cluster.
+Many artifacts define the Helm charts in terms of their upstream open source versions (if they're actively maintained, allow for required customization and fit Plural's quality standards)
+as well as other helper charts, e.g. from Plural's [Module Library](/adding-new-application/module-library).
 If any additional resources are necessary, they can be added and templated in the same manner as with any other Helm chart.
 Any default chart parametrization goes into your standard `values.yaml` file, most prominently resource requirements or limits, labels, annotations, entrypoint customizations, and so on.
 
@@ -98,17 +99,17 @@ This enables us to parametrize values for resources that depend on application c
 The ARN of an AWS role or bucket, or VPC subnet ids are common examples for this.
 Another supported use case is to pass output from other Plural deployed applications that live in the same cluster,
 or configuration that you can query from the Plural API, e.g. OIDC config if you're using Plural as an OIDC provider for your apps, too.
-See [Templating](###Templating) for how powerful this additional templating layer can be.
+See [Templating](/adding-new-application/templating) for how powerful this additional templating layer can be.
 
-Plural leverages dependency tracking of applications to achieve a high degree of resource efficiency and modularity.
+Plural leverages dependency tracking of applications to achieve a high degree of resource efficiency and deduplication.
 Dependencies between artifacts are defined in the recipe files (see below).
-At the level of the Helm charts and Terraform modules the cross-application dependencies are tracked in a dedicated `deps.yaml` at each chart's or module's top-level directory.
+Dependencies are also tracked between the Helm charts and Terraform modules of other applications in a dedicated `deps.yaml` file in each chart's or module's directory.
 For example, for Dagster's Helm chart you would list required dependencies on:
 - the `bootstrap` application's Helm chart 
 - the `ingress-nginx` application's Helm chart
 - the `postrges` operator application's Helm chart
 
-as well as optional dependencies the Dagster application's own Terraform modules to convey the intent that those are installed before the Helm chart.
+as well as optional dependencies on Dagster's own Terraform modules to convey intent that those are installed before the Helm chart.
 
 ```yaml
 apiVersion: plural.sh/v1alpha1
@@ -151,10 +152,10 @@ spec:
 ## Terraform
 
 The `terraform` directory contains the app's provider-specific terraform modules that encapsulate all application components that do not (or cannot) live inside the cluster.
-For each cloud provider that the artifact offers a bundle for there will be one under the related directory name.
+For each cloud provider, that the artifact offers a bundle for, there will be one under the related directory name.
 Most commonly you'd find object storage alongside their IAM resources, but sometimes also Kubernetes resources like service accounts,
 if their deployment cannot be achieved through the artifact's Helm chart in a convenient manner.
-> One peculiarity about the terraform modules is that at the very least they need to contain the Kubernetes namespace for your application.
+> One peculiarity about the Terraform modules is that, at the very least, they need to contain the Kubernetes namespace for your application.
   This is because during a `plural deploy` with the Plural CLI the `terraform apply` will always run before the `helm install` step.
 
 Just like the Helm chart, the Terraform modules also contain a `deps.yaml` file that inform the Plural API about dependencies on other modules.
@@ -204,11 +205,11 @@ tags:
 
 The metadata in this file informs the Plural API about the application this artifact envelopes.
 It will store its name, category and description, where it can find the icon and docs to display in the marketplace,
-the notes template to prompt after installation, as well as links to any upstream git repository or homepage if applicable.
+the notes template to prompt after installation, as well as links to any upstream git repository or homepage (if applicable).
 
 `oauthSettings` specifies the URI format for the OIDC callback address and informs the Plural API how to setup the OIDC endpoint for your application if you use it.
 > Behind the scenes, every `plural bundle install` triggers the OIDC client creation when you answer with `yes` on the OIDC prompt.
-  This happens, because every Client needs to be created before a `plural build` which then inputs the client info into the helm chart.
+  This happens, because every client needs to be created before a `plural build` which then inputs the client info into the helm chart.
 
 The `private` flag controls whether the artifact's bundles are published publicly or privately on a `plural push`.
 It should be set to the same value as the `private` flag in inside the `repository.yaml`.
@@ -253,7 +254,7 @@ It informs the Plural API about the bundle's parameter signature, metadata, depe
 Let's step through this file.
 
 - `provider` defines the targeted cloud provider of this recipe.
-- For every artifact one of the recipes can be marked as `primary` which will make it possible to install with simply a `plural bundle install <app_name>` (leaving out the `<bundle>`).
+- For every artifact one of the recipes can be marked as `primary` which will make it possible to simply install with a `plural bundle install <app_name>` (leaving out the `<bundle>`).
 - The apps listed in `dependencies` tell Plural on which other Plural bundles this bundle depends on.
   > Most bundles depend on the installation of other Plural applications. For example, every bundle will at least depend on the bootstrap application that packages the cluster itself.
 - Similar to `oauthSettings` in the `repository.yaml`, `oidcSettings` in the recipe YAML should specify the same configuration at the bundle level.
@@ -263,6 +264,7 @@ Let's step through this file.
   For examples on available types check other Plural artifacts.
   The Plural CLI will store the passed values in the according section in the `context.yaml` as discussed above.
 - `sections[0].items` lists the chart and module directories in the `helm` or `terraform` directories that are part of this bundle.
+
 > A bundle can technically have multiple sections, but this feature's not yet used.
 
 ```yaml

pages/adding-new-application/publishing.md

@@ -1,4 +1,6 @@
-# Publishing a Plural Artifact
+---
+title: Publishing a Plural Artifact
+---
 
 Every Plural account holder can act as a publisher to publish artifacts and in that way contribute open source applications to Plural's marketplace.
 If you don't want to publish an application publicly straight away and make it available to everybody you can first test it by releasing it privately whereby only users of your Plural account can install it.

pages/adding-new-application/templating.md

@@ -1,6 +1,13 @@
-# Templating
+---
+title: Templating
+description: >-
+  The two main functionalities that make Plural work are dependency tracking between DevOps tools (Helm and Terraform) and templating.
+  This guide serves as a reference for how you can leverage this feature.
+---
 
-The next example is a snippet of the `values.yaml.tpl` file for Grafana:
+In [Plural Artifact Structure](/adding-new-application/plural-artifact-structure) we layed out how an artifact can be paremtrized.
+
+The example is a snippet of the `values.yaml.tpl` file for Grafana:
 
 ```yaml
 grafana:

src/NavData.tsx

@@ -177,7 +177,11 @@ const rootNavData: NavMenu = deepFreeze([
         href: '/adding-new-application',
         title: 'Contribute a New Application to the Plural Catalog',
         sections: [
-          { href: '/adding-new-application/guide', title: 'Guide' },
+          { href: '/adding-new-application/background-app-install', title: 'Background on Application Installations'},
+          { href: '/adding-new-application/application-artifact-package', title: 'Plural Artifact Structure'},
+          { href: '/adding-new-application/templating', title: 'Plural Artifact Templating'},
+          { href: '/adding-new-application/guide', title: 'Guide on Creating a New Application Artifact' },
+          { href: '/adding-new-application/publishing', title: 'Guide on Publishing a Plural Artifact'},
           {
             href: '/adding-new-application/plural-custom-resources',
             title: 'Plural Custom Resources',