docs: Adjust NATS to new content guidelines (kyma-project#244)

* adjust NATS to new content guidelines * adjust headlines in README * Back to Kyma Home * adjust sidebar * fix NATS spelling Co-authored-by: Natalia Sitko <[email protected]> --------- Co-authored-by: Natalia Sitko <[email protected]>
friedrichwilken · Dec 11, 2023 · b295ce5 · b295ce5
1 parent e4c497b
commit b295ce5
Show file tree

Hide file tree

Showing 10 changed files with 62 additions and 59 deletions.
diff --git a/README.md b/README.md
@@ -8,15 +8,15 @@ Manages the lifecycle of a NATS JetStream deployment.
 
 NATS Manager is a standard Kubernetes operator that observes the state of NATS JetStream deployment and reconciles its state according to the desired state.
 
-### How it works
+### How It Works
 
 This project aims to follow the [Kubernetes Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/).
 
 It uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/), which provide a reconcile function responsible for synchronizing resources until the desired state is reached on the cluster.
 
 This project is scaffolded using [Kubebuilder](https://book.kubebuilder.io), and all the Kubebuilder [`makefile` helpers](https://book.kubebuilder.io/reference/makefile-helpers.html) can be used.
 
-## Install
+## Installation
 
 1. To install the latest version of the NATS manager on your cluster, run:
 
@@ -118,7 +118,7 @@ You’ll need a Kubernetes cluster to run against. You can use [k3d](https://k3d
 
 > **NOTE:** Your NATS Manager automatically uses the current context in your kubeconfig file, that is, whatever cluster `kubectl cluster-info` shows.
 
-### Deploy on the cluster
+### Deploy on the Cluster
 
 1. Download Go packages:
 
@@ -166,7 +166,7 @@ To delete the CRDs from the cluster:
 make uninstall
 ```
 
-### Deploy NATS Manager module with [Kyma Lifecycle Manager](https://github.com/kyma-project/lifecycle-manager/tree/main)
+### Deploy NATS Manager Module With [Kyma Lifecycle Manager](https://github.com/kyma-project/lifecycle-manager/tree/main)
 
 1. Deploy the Lifecycle Manager to the Kubernetes cluster:
 
@@ -202,7 +202,7 @@ make uninstall
      kubectl get -n kyma-system kyma
      ```
 
-### Uninstall NATS Manager module with [Kyma Lifecycle Manager](https://github.com/kyma-project/lifecycle-manager/tree/main)
+### Uninstall NATS Manager Module With [Kyma Lifecycle Manager](https://github.com/kyma-project/lifecycle-manager/tree/main)
 
 1. Delete NATS Custom Resource (CR) from the Kubernetes cluster (if exists):
 
@@ -237,7 +237,7 @@ make uninstall
      kubectl get -n kyma-system kyma
      ```
 
-## E2E tests
+## E2E Tests
 
 > **NOTE:** Because the E2E tests need a Kubernetes cluster to run on, they are separated from the remaining tests and are only executed if the `e2e` build tags are passed.
 

diff --git a/docs/contributor/development.md b/docs/contributor/development.md
@@ -14,12 +14,10 @@ Projects created by Kubebuilder contain a Makefile with tooling that must be loc
 - [golangci-lint](https://golangci-lint.run/)
 
 ## Available Commands
+
 Commands are available for easier development and installation of the NATS Manager.
 To find out which commands are available and for some more details about each command, run:
 
 ```bash
 make help
 ```
-
-
-
diff --git a/docs/contributor/governance.md b/docs/contributor/governance.md
@@ -3,7 +3,7 @@
 Some quality aspects are covered by automated verification, so you must locally execute tooling before a commit.
 This document guides you through the development flow.
 
-## Modifying the API definitions
+## Modifying the API Definitions
 
 This project uses the [controller-gen](https://book.kubebuilder.io/reference/controller-gen.html) tool provided by [Kubebuilder](https://book.kubebuilder.io/).
 To modify the API definitions, you must adapt the ["marker comments"](https://book.kubebuilder.io/reference/markers.html) in the Go code.
@@ -13,15 +13,17 @@ The rules are written using the [Common Expression Language](https://github.com/
 For further information and examples, look to the [Kubernetes documentation](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#validation) of validation rules and the CEL [language definition](https://github.com/google/cel-spec/blob/v0.10.0/doc/langdef.md).
 
 After the modifications, run the following command to generate the new manifests such as CRs and CRDs:
-   ```sh
-   make manifests
-   ```
+
+```sh
+make manifests
+```
 
 If changes to the `runtime.Object` interface were made, the `DeepCopy` functions must be updated as well.
 The generation is controlled by [Kubebuilder markers](https://book.kubebuilder.io/reference/markers/object.html?highlight=deep#objectdeepcopy).
-   ```sh
-   make generate
-   ```
+
+```sh
+make generate
+```
 
 ## Sourcecode Linting
 

diff --git a/docs/contributor/installation.md b/docs/contributor/installation.md
@@ -2,9 +2,9 @@
 
 There are several ways to install the NATS Manager.
 For development, you must run some make targets beforehand.
-For information about the prerequisites, refer to [Development](./development.md) and for a detailed guide to the development flow, visit [Governance](./governance.md).
+For information about the prerequisites, refer to [Development](./development.md), and for a detailed guide to the development flow, visit [Governance](./governance.md).
 
-## Run the manager on a (k3d) cluster using a Docker image
+## Run the NATS Manager on a (k3d) Cluster Using a Docker Image
 
 ### Installation
 
@@ -80,7 +80,7 @@ For information about the prerequisites, refer to [Development](./development.md
    make uninstall
    ```
 
-## Run the manager on a cluster using the Go runtime environment
+## Run the NATS Manager on a Cluster Using the Go Runtime Environment
 
 ### Installation
 
@@ -114,7 +114,7 @@ Remove the resources.
    make uninstall
    ```
 
-## Run the NATS Manager using Kyma's Lifecycle Manager
+## Run the NATS Manager Using Kyma’s Lifecycle Manager
 
 [Kyma's Lifecycle Manager](https://github.com/kyma-project/lifecycle-manager) helps manage the lifecycle of each module in the cluster and can be used to install the NATS Manager.
 

diff --git a/docs/contributor/testing.md b/docs/contributor/testing.md
@@ -87,7 +87,6 @@ The E2E test consists of four consecutive steps. If desired, you can run them in
    make e2e-cleanup
    ```
 
-
 ## CI/CD
 
 This project uses [Prow](https://docs.prow.k8s.io/docs/) and [GitHub Actions](https://docs.github.com/en/actions) as part of the development cycle.

diff --git a/docs/contributor/troubleshooting.md b/docs/contributor/troubleshooting.md
@@ -2,26 +2,24 @@
 
 This document contains tips and tricks to common problems with the NATS Manager and will be updated continuously.
 
-## Troubleshooting: Installing NATS Manager using a Docker image
+## Troubleshooting: Installing NATS Manager Using a Docker Image
 
-### Error while deploying the NATS Manager
+### Error While Deploying the NATS Manager
 
 **Symptom:** The `make deploy` step fails with the following error message:
 
 `Error from server (NotFound): error when creating "STDIN": namespaces kyma-system not found`
 
-**Cause:** The Namespace of the Deployment does not exist yet.
+**Cause:** The namespace of the Deployment does not exist yet.
 
-**Remedy:** Create the Namespace.
+**Remedy:** Create the namespace.
 
    ```sh
    kubectl create ns kyma-system
    ```
 
-## Reach out to us
+## Reach Out to Us
 
-If you encounter an issue or want to report a bug, please create a [GitHub issue](https://github.com/kyma-project/nats-manager/issues) with background information and
-steps how to reproduce.
+If you encounter an issue or want to report a bug, please create a [GitHub issue](https://github.com/kyma-project/nats-manager/issues) with background information and steps how to reproduce.
 
-If you want to contact the eventing team directly, you can reach us via Slack [Eventing channel](https://kyma-community.slack.com/archives/CD1C9GZMK)
-or tag us `@kyma-eventing` in the Slack [Kyma Tech channel](https://sap-ti.slack.com/archives/C0140PCSJ5Q)
+If you want to contact the eventing team directly, you can reach us via Slack [Eventing channel](https://kyma-community.slack.com/archives/CD1C9GZMK), or tag us `@kyma-eventing` in the Slack [Kyma Tech channel](https://sap-ti.slack.com/archives/C0140PCSJ5Q).
diff --git a/docs/user/01-manager.md b/docs/user/01-manager.md
@@ -1,36 +1,35 @@
 # NATS Manager
 
-This module ships the NATS Manager.
+The Kyma NATS module ships the NATS Manager.
 
 ## Module Lifecycle
 
 ### Starting NATS Manager
 
-Upon starting the NATS Manager, the controller (following the [Kubebuilder concept](https://book.kubebuilder.io/architecture.html)) creates, watches and reconciles the following resources:
+Upon starting the NATS Manager, the controller (following the [Kubebuilder concept](https://book.kubebuilder.io/architecture.html)) creates, watches, and reconciles the following resources:
 
-   - ConfigMap (cm)
-   - Secret (sc)
-   - Service (sv)
-   - Stateful Set (sts)
-   - DestinationRule (dr, [Istio](https://istio.io))
+- ConfigMap (cm)
+- Secret (sc)
+- Service (sv)
+- Stateful Set (sts)
+- DestinationRule (dr, [Istio](https://istio.io))
 
 ![Start NATS manager](./assets/Start_nats_manager.drawio.svg)
 
-### Reacting to NATS CR changes
+### Reacting to NATS CR Changes
 
 The NATS Manager reacts to changes of the NATS CR to adapt the resources mentioned above to the desired state.
 For details how to configure NATS using the CR, visit the [Configuration documentation](./02-configuration.md).
 
 ![Reacting to NATS CR changes](./assets/reacting_to_nats_cr_changes.drawio.svg)
 
-### Reacting to resource changes
+### Reacting to Resource Changes
 
 When resources are changed or deleted, the controller reacts by restoring the defaults according to the NATS CR.
 Thus, if you want to change the resources, you must edit the NATS CR; you cannot change the resources directly.
 
 ![Reacting to resource changes](assets/reacting_to_resource_changes.drawio.svg)
 
-
-### Overview: NATS Manager watches resources
+### Overview: NATS Manager Watches Resources
 
   ![NM watches resources](assets/NC_watches_resources.drawio.svg)
diff --git a/docs/user/10-nats-server-system-events.md b/docs/user/10-nats-server-system-events.md
@@ -1,26 +1,33 @@
-# Acquiring NATS server system account credentials
+# Acquiring NATS Server System Account Credentials
 
 ## Context
 
-Accessing certain resources in NATS requires [`system_account` privileges](https://docs.nats.io/running-a-nats-service/configuration/sys_accounts). Kyma automatically generates a `system account` user using a Secret dubbed `eventing-nats-secret` in the `kyma-system` Namespace.
+Accessing certain resources in NATS requires [`system_account` privileges](https://docs.nats.io/running-a-nats-service/configuration/sys_accounts). Kyma automatically generates a `system account` user using a Secret dubbed `eventing-nats-secret` in the `kyma-system` namespace.
 
 ## Procedure
 
-To acquire the credentials, run the following command:
+To get the credentials, run:
 
 ```bash
 kubectl get secrets -n kyma-system eventing-nats-secret -ogo-template='{{index .data "resolver.conf"|base64decode}}'| grep 'user:' | tr -d '{}'
 ```
 
-### Result: 
+### Result
+
 You get the credentials for the `system account` user in the following format:
+
 ```bash
 user: admin, password: <your password>
 ```
-### Next steps:
+
+### Next Steps
+
 1. To access the NATS server with the [nats-cli tool](https://github.com/nats-io/natscli), forward its port:
+
    ```bash
    kubectl port-forward -n kyma-system svc/eventing-nats 4222
+
 2. To send your NATS commands, pass the credentials:
+
    ```bash
    nats server info --user admin --password <your password>
diff --git a/docs/user/README.md b/docs/user/README.md
@@ -1,4 +1,4 @@
-# NATS module
+# NATS Module
 
 This module ships the NATS Manager, which is responsible for managing the lifecycle of a [NATS JetStream](https://docs.nats.io/nats-concepts/jetstream) deployment.
 It observes the state of the NATS cluster and reconciles its state according to the desired state.
@@ -10,13 +10,13 @@ Kyma Eventing can use NATS as a backend to process events and send them to subsc
 
 ## Documentation Overview
 
-   - [General information about the NATS Manager](./01-manager.md)
-   - [Details how to configure the NATS module](./02-configuration.md)
+- [General information about the NATS Manager](./01-manager.md)
+- [Details how to configure the NATS module](./02-configuration.md)
 
 There is further documentation including more technical details aimed at possible contributors:
 
-   - [General information about the setup](../contributor/development.md)
-   - [Guide to the project governance](../contributor/governance.md)
-   - [Installation guide](../contributor/installation.md)
-   - [Information about the test coverage](../contributor/testing.md)
-   - [Troubleshooting](../contributor/troubleshooting.md)
+- [General information about the setup](../contributor/development.md)
+- [Guide to the project governance](../contributor/governance.md)
+- [Installation guide](../contributor/installation.md)
+- [Information about the test coverage](../contributor/testing.md)
+- [Troubleshooting](../contributor/troubleshooting.md)
diff --git a/docs/user/_sidebar.md b/docs/user/_sidebar.md
@@ -1,5 +1,5 @@
-- [Home](/)
-- [NATS Manager](README.md)
-- [Module Lifecycle](01-manager.md)
-- [Module Configuration](02-configuration.md)
-- [Acquiring NATS server system account credentials](10-nats-server-system-events.md)
+- [Back to Kyma Home](/)
+- [NATS Manager](/nats-manager/user/README.md)
+- [Module Lifecycle](/nats-manager/user/01-manager.md)
+- [Module Configuration](/nats-manager/user/02-configuration.md)
+- [Acquiring NATS Server System Account Credentials](/nats-manager/user/10-nats-server-system-events.md)
-Original file line number
+Diff line change
@@ Expand Up @@
        make e2e-cleanup
        ```
     ## CI/CD
     This project uses [Prow](https://docs.prow.k8s.io/docs/) and [GitHub Actions](https://docs.github.com/en/actions) as part of the development cycle.
@@ Expand Down @@