docs: format headings and placeholders (#772)

Author: staceysalamon-aiven

README.md

@@ -27,7 +27,7 @@ spec:
   connInfoSecretTarget:
     name: pg-connection
 
-  project: <your-project-name>
+  project: PROJECT_NAME
   cloudName: google-europe-west1
   plan: hobbyist
   maintenanceWindowDow: friday

docs/docs/authentication.md

@@ -5,7 +5,7 @@ weight: 10
 ---
 
 To get authenticated and authorized, set up the communication between the Aiven Operator for Kubernetes and Aiven by
-using a token stored in a Kubernetes secret. You can then refer to the secret name on every custom resource in
+using a token stored in a Kubernetes Secret. You can then refer to the Secret name on every custom resource in
 the `authSecretRef` field.
 
 **If you don't have an Aiven account yet, sign
@@ -19,10 +19,10 @@ authentication token.
 
 2\. Create the Kubernetes Secret
 
-The following command creates a secret named `aiven-token` with a `token` field containing the authentication token:
+The following command creates a Secret named `aiven-token` with a `token` field containing the authentication token:
 
 ```shell
-kubectl create secret generic aiven-token --from-literal=token="<your-token-here>"
+kubectl create secret generic aiven-token --from-literal=token="TOKEN"
 ```
 
 When managing your Aiven resources, we will be using the created Secret in the `authSecretRef` field. It will look like
@@ -52,6 +52,6 @@ kind: PostgreSQL
 metadata:
   name: pg-sample
 spec:
-  project: <your-project-name-here>
+  project: PROJECT_NAME
   [ ... ]
 ```

docs/docs/contributing/developer-guide.md

@@ -4,7 +4,7 @@ linkTitle: "Developer guide"
 weight: 10
 ---
 
-## Getting Started
+## Get Started
 
 To get started, make sure you have a working [Go environment](https://golang.org/doc/install) and clone the repository:
 
@@ -103,7 +103,7 @@ kubectl apply -f aiven-pg.yaml
 You should see the service be created on Aiven's side using either [Aiven Console](https://console.aiven.io/) or Aiven CLI:
 
 ```{ .sh .no-copy }
-$ avn project switch <your-project-name>
+$ avn project switch PROJECT_NAME
 $ avn service list
 SERVICE_NAME      SERVICE_TYPE  STATE       CLOUD_NAME           PLAN      CREATE_TIME           UPDATE_TIME           NOTIFICATIONS
 ================  ============  ==========  ===================  ========  ====================  ====================  =============

docs/docs/installation/helm.md

@@ -1,6 +1,6 @@
 ---
-title: "Installing with Helm (recommended)"
-linkTitle: "Installing with Helm (recommended)"
+title: "Install with Helm (recommended)"
+linkTitle: "Install with Helm (recommended)"
 weight: 10
 ---
 
@@ -16,7 +16,7 @@ First add the [Aiven Helm repository](https://github.com/aiven/aiven-charts):
 helm repo add aiven https://aiven.github.io/aiven-charts && helm repo update
 ```
 
-### Installing Custom Resource Definitions
+### Install Custom Resource Definitions
 
 ```shell
 helm install aiven-operator-crds aiven/aiven-operator-crds
@@ -37,7 +37,7 @@ databases                          aiven.io/v1alpha1   true         Database
 ... < several omitted lines >
 ```
 
-### Installing the Operator
+### Install the Operator
 
 ```shell
 helm install aiven-operator aiven/aiven-operator
@@ -73,7 +73,7 @@ helm install aiven-operator aiven/aiven-operator --set webhooks.enabled=false
 
 Please refer to the [values.yaml](https://github.com/aiven/aiven-charts/blob/main/charts/aiven-operator/values.yaml) of the chart.
 
-#### Installing without full cluster administrator access
+#### Install without full cluster administrator access
 
 If the person installing the Helm chart does not have the necessary permissions to create cluster-wide resources such as `ClusterRole` and `ClusterRoleBinding`, a cluster administrator can manually install these roles. This ensures that the operator can function properly.
 

docs/docs/installation/kubectl.md

@@ -1,6 +1,6 @@
 ---
-title: "Installing with kubectl"
-linkTitle: "Installing with kubectl"
+title: "Install with kubectl"
+linkTitle: "Install with kubectl"
 weight: 15
 ---
 

docs/docs/installation/uninstalling.md

@@ -1,6 +1,6 @@
 ---
-title: "Uninstalling"
-linkTitle: "Uninstalling"
+title: "Uninstall"
+linkTitle: "Uninstall"
 weight: 90
 ---
 
@@ -13,21 +13,19 @@ Depending on your installation, please follow one of:
 - [Helm](../installation/helm.md#uninstalling)
 - [kubectl](../installation/kubectl.md#uninstalling)
 
-## Dealing with expired tokens
+## Expired tokens
 
 Aiven resources need to have an accompanying secret that contains the token that is used to authorize the manipulation of that resource.
 If that token expired then you will not be able to delete the custom resource and deletion will also hang until the situation is resolved.
 The recommended approach to deal with that situation is to patch a valid token into the secret again so that proper cleanup of aiven resources can take place.
 
 ## Hanging deletions
 
-To protect the secrets that the operator is using from deletion, it adds the [finalizer](https://kubernetes.io/docs/concepts/overview/working-with-objects/finalizers/) `finalizers.aiven.io/needed-to-delete-services` to the secret.
-This solves a race condition that happens when deleting a namespace, where there is a possibility of the secret getting deleted before the resource that uses it.
-When the controller is deleted it may not cleanup the finalizers from all secrets.
-If there is a secret with this finalizer blocking deletion of a namespace, for now please do
+To protect the Secrets that the operator is using from deletion, it adds the [finalizer](https://kubernetes.io/docs/concepts/overview/working-with-objects/finalizers/) `finalizers.aiven.io/needed-to-delete-services` to the Secret.
+This solves a race condition that happens when deleting a namespace, where there is a possibility of the Secret getting deleted before the resource that uses it.
+When the controller is deleted it may not cleanup the finalizers from all Secrets.
+If there is a Secret with this finalizer blocking deletion of a namespace, you can remove the finalizer by running:
 
 ```shell
 kubectl patch secret <offending-secret> -p '{"metadata":{"finalizers":null}}' --type=merge
 ```
-
-to remove the finalizer.

docs/docs/resources/cassandra.md

@@ -9,7 +9,7 @@ Aiven for Apache Cassandra® is a distributed database designed to handle large
 !!! note
     Before going through this guide, make sure you have a [Kubernetes cluster](../installation/prerequisites.md) with the operator installed (see instructions for [helm](../installation/helm.md) or [kubectl](../installation/kubectl.md)), and a [Kubernetes Secret with an Aiven authentication token](../authentication.md).
 
-## Creating a Cassandra instance
+## Create a Cassandra instance
 
 1\. Create a file named `cassandra-sample.yaml`, and add the following content:
 
@@ -29,7 +29,7 @@ spec:
     name: cassandra-secret
 
   # add your Project name here
-  project: <your-project-name>
+  project: PROJECT_NAME
 
   # cloud provider and plan of your choice
   # you can check all of the possibilities here https://aiven.io/pricing
@@ -81,7 +81,7 @@ Status:
 
 The resource can be in the `REBUILDING` state for a few minutes. Once the state changes to `RUNNING`, you can access the resource.
 
-## Using the connection Secret
+## Use the connection Secret
 
 For your convenience, the operator automatically stores the Cassandra connection information in a Secret created with the
 name specified on the `connInfoSecretTarget` field.
@@ -131,7 +131,7 @@ The output is similar to the following:
 }
 ```
 
-## Creating a Cassandra user
+## Create a Cassandra user
 
 You can create service users for your instance of Aiven for Apache Cassandra. Service users are unique to this instance and are not shared with any other services.
 
@@ -150,7 +150,7 @@ spec:
   connInfoSecretTarget:
     name: cassandra-service-user-secret
 
-  project: <your-project-name>
+  project: PROJECT_NAME
   serviceName: cassandra-sample
 ```
 

docs/docs/resources/kafka/connect.md

@@ -14,7 +14,7 @@ This section involves a few different Kubernetes CRDs:
 4. A `PostgreSQL` used as a sink to receive messages from `Kafka`
 5. A `KafkaConnector` to finally connect the `Kafka` with the `PostgreSQL`
 
-## Creating the resources
+## Create the resources
 
 Create a file named `kafka-sample-connect.yaml` with the following content:
 
@@ -34,7 +34,7 @@ spec:
     name: kafka-auth
 
   # add your Project name here
-  project: <your-project-name>
+  project: PROJECT_NAME
 
   # cloud provider and plan of your choice
   # you can check all of the possibilities here https://aiven.io/pricing
@@ -60,7 +60,7 @@ spec:
     name: aiven-token
     key: token
 
-  project: <your-project-name>
+  project: PROJECT_NAME
   serviceName: kafka-sample-connect
 
   replication: 2
@@ -81,7 +81,7 @@ spec:
     key: token
 
   # add your Project name here
-  project: <your-project-name>
+  project: PROJECT_NAME
 
   # cloud provider and plan of your choice
   # you can check all of the possibilities here https://aiven.io/pricing
@@ -106,7 +106,7 @@ spec:
     name: aiven-token
     key: token
 
-  project: <your-project-name>
+  project: PROJECT_NAME
 
   # indicates the type of the integration
   integrationType: kafka_connect
@@ -134,7 +134,7 @@ spec:
     name: pg-connection
 
   # add your Project name here
-  project: <your-project-name>
+  project: PROJECT_NAME
 
   # cloud provider and plan of your choice
   # you can check all of the possibilities here https://aiven.io/pricing
@@ -160,7 +160,7 @@ spec:
     name: aiven-token
     key: token
 
-  project: <your-project-name>
+  project: PROJECT_NAME
 
   # the Kafka cluster name
   serviceName: kafka-sample-connect

docs/docs/resources/kafka/index.md

@@ -12,7 +12,7 @@ you can get up and running with a suitably sized Apache Kafka service in a few m
     operator installed (see instructions for [helm](../../installation/helm.md) or [kubectl](../../installation/kubectl.md)),
     and a [Kubernetes Secret with an Aiven authentication token](../../authentication.md).
 
-## Creating a Kafka instance
+## Create a Kafka instance
 
 1\. Create a file named `kafka-sample.yaml`, and add the following content:
 
@@ -32,7 +32,7 @@ spec:
     name: kafka-auth
 
   # add your Project name here
-  project: <your-project-name>
+  project: PROJECT_NAME
 
   # cloud provider and plan of your choice
   # you can check all of the possibilities here https://aiven.io/pricing
@@ -65,12 +65,12 @@ The output has the project name and state, similar to the following:
 ```{ .shell .no-copy }
 
 NAME           PROJECT          REGION                PLAN        STATE
-kafka-sample   <your-project>   google-europe-west1   startup-2   RUNNING
+kafka-sample   PROJECT_NAME   google-europe-west1   startup-2   RUNNING
 ```
 
 After a couple of minutes, the `STATE` field is changed to `RUNNING`, and is ready to be used.
 
-## Using the connection Secret
+## Use the connection Secret
 
 For your convenience, the operator automatically stores the Kafka connection information in a Secret created with the
 name specified on the `connInfoSecretTarget` field.
@@ -119,7 +119,7 @@ The output is similar to the following:
 }
 ```
 
-## Testing the connection
+## Test the connection
 
 You can verify your access to the Kafka cluster from a Pod using the authentication data from the `kafka-auth` Secret. [kcat](https://github.com/edenhill/kcat) is used for our examples below.
 
@@ -197,7 +197,7 @@ Metadata for all topics (from broker -1: ssl://kafka-sample-your-project.aivencl
  0 topics:
 ```
 
-## Creating a `KafkaTopic` and `KafkaACL`
+## Create a `KafkaTopic` and `KafkaACL`
 
 To properly produce and consume content on Kafka, you need topics and ACLs. The operator supports both with
 the `KafkaTopic` and `KafkaACL` resources.
@@ -216,7 +216,7 @@ spec:
     name: aiven-token
     key: token
 
-  project: <your-project-name>
+  project: PROJECT_NAME
   serviceName: kafka-sample
 
   # here we can specify how many partitions the topic should have
@@ -258,7 +258,7 @@ spec:
     name: kafka-crab-connection
 
   # the Aiven project the user is related to
-  project: <your-project-name>
+  project: PROJECT_NAME
 
   # the name of our Kafka Service
   serviceName: kafka-sample
@@ -273,7 +273,7 @@ spec:
     name: aiven-token
     key: token
 
-  project: <your-project-name>
+  project: PROJECT_NAME
   serviceName: kafka-sample
 
   # the username from the ServiceUser above
@@ -292,7 +292,7 @@ To create the `crab` user and its permissions, execute the following command:
 kubectl apply -f kafka-acl-user-crab.yaml
 ```
 
-## Producing and consuming events
+## Produce and consume events
 
 Using the previously created `KafkaTopic`, `ServiceUser`, `KafkaACL`, you can produce and consume events.
 

docs/docs/resources/kafka/schema.md

@@ -4,7 +4,7 @@ linkTitle: "Kafka Schema"
 weight: 40
 ---
 
-## Creating a `KafkaSchema`
+## Create a `KafkaSchema`
 
 Aiven develops and maintain [Karapace](https://github.com/aiven/karapace), an open source implementation of Kafka REST
 and schema registry. Is available out of the box for our managed Kafka service.
@@ -28,7 +28,7 @@ spec:
   connInfoSecretTarget:
     name: kafka-auth
 
-  project: <your-project-name>
+  project: PROJECT_NAME
   cloudName: google-europe-west1
   plan: startup-2
   maintenanceWindowDow: friday
@@ -61,7 +61,7 @@ spec:
     name: aiven-token
     key: token
 
-  project: <your-project-name>
+  project: PROJECT_NAME
   serviceName: kafka-sample-schema
 
   # the name of the Schema
@@ -100,7 +100,7 @@ The output is similar to the following:
 
 ```{ .shell .no-copy }
 NAME           SERVICE NAME   PROJECT          SUBJECT    COMPATIBILITY LEVEL   VERSION
-kafka-schema   kafka-sample   <your-project>   MySchema   BACKWARD              1
+kafka-schema   kafka-sample   PROJECT_NAME   MySchema   BACKWARD              1
 ```
 
 Now you can follow the instructions to [use a schema registry in Java](https://aiven.io/docs/products/kafka/howto/schema-registry) on how to use the schema created.