From 9832fbae34f945ae975ac37c23de356380be5099 Mon Sep 17 00:00:00 2001 From: mmitoraj Date: Tue, 22 Oct 2024 13:47:11 +0200 Subject: [PATCH 01/13] Add the operator folder to the template --- docs/README.md | 11 +++++++---- docs/operator/README.md | 1 + docs/operator/cn/01-installation.md | 15 +++++++++++++++ docs/operator/cn/02-update.md | 15 +++++++++++++++ docs/operator/cn/03-operations.md | 3 +++ docs/operator/cn/04-troubleshooting.md | 8 ++++++++ docs/operator/cn/README.md | 10 ++++++++++ docs/operator/ns2/01-installation.md | 15 +++++++++++++++ docs/operator/ns2/02-update.md | 15 +++++++++++++++ docs/operator/ns2/03-operations.md | 3 +++ docs/operator/ns2/04-troubleshooting.md | 8 ++++++++ docs/operator/ns2/README.md | 10 ++++++++++ 12 files changed, 110 insertions(+), 4 deletions(-) create mode 100644 docs/operator/README.md create mode 100644 docs/operator/cn/01-installation.md create mode 100644 docs/operator/cn/02-update.md create mode 100644 docs/operator/cn/03-operations.md create mode 100644 docs/operator/cn/04-troubleshooting.md create mode 100644 docs/operator/cn/README.md create mode 100644 docs/operator/ns2/01-installation.md create mode 100644 docs/operator/ns2/02-update.md create mode 100644 docs/operator/ns2/03-operations.md create mode 100644 docs/operator/ns2/04-troubleshooting.md create mode 100644 docs/operator/ns2/README.md diff --git a/docs/README.md b/docs/README.md index 84aca7b..a3b3fec 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,12 +2,14 @@ ## Overview -The `docs` folder contains two subfolders - `user` and `contributor`. +The `docs` folder contains three subfolders - `user`, `contributor` and `operator`. -The `user` subfolder contains the end-user documentation, which is displayed on the [Kyma website](https://kyma-project.io/#/). Depending on your module needs, the subfolder must include overview, usage, or technical reference documents. To display the content on the website properly, create a `_sidebar.md` file in the `user` subfolder and list the documents it contains there. For more information on how to publish user documentation, follow [this guide](https://github.com/kyma-project/community/blob/main/docs/guidelines/content-guidelines/01-user-docs.md). +The `user` subfolder contains the end-user documentation, which is displayed on the [Kyma website](https://kyma-project.io/#/) and in the SAP Help Portal. Depending on your module needs, the subfolder must include overview, usage, or technical reference documents. To display the content on the website properly, create a `_sidebar.md` file in the `user` subfolder and list the documents it contains there. For more information on how to publish user documentation, follow [this guide](https://github.com/kyma-project/community/blob/main/docs/guidelines/content-guidelines/01-user-docs.md). The `contributor` subfolder includes any developer-related documentation to help them manually install, develop, and operate a module. +The `operator` subfolder is mandatory only if your module/component is delivered to restricted markets. The subfolder includes documentation relevant for the respective operators. + To have a common structure across all modules, all documents must be properly numbered according to the following structure: > **NOTE:** It is suggested to use the following titles if you have the content that matches them; otherwise use your own, more suitable titles, or simply skip the ones you find irrelevant. @@ -32,8 +34,9 @@ where `xx` is the number of the given document. For example: 02-30-use-metrics (...) ``` + > **NOTE:** Before introducing [docsify](https://docsify.js.org/#/?id=docsify), we agreed to use the `10`, `20`, `30` numbering. It was to help maintain the proper order of docs if they were rendered automatically on the website. With docsify, you manually add the content to the `_sidebar.md` file, and docs are displayed in the order you add them. However, this numbering is still recommended to have the unified structure of the docs in the module repositories. - + If you have other content that does not fit into the above topics, create your own 04-10-module-specific document(s). -You can divide your documentation into subfolders to avoid having too many documents in one `docs/user` or `docs/contributor` folder. For example, if you have many technical reference documents, you can create a `technical reference` subfolder in `docs/user` and keep relevant documentation there. Each subfolder in the `user` folder must have its own `_sidebar.md` file with the links to the main module page and the list of docs it contains. \ No newline at end of file +You can divide your documentation into subfolders to avoid having too many documents in one `docs/user` or `docs/contributor` folder. For example, if you have many technical reference documents, you can create a `technical reference` subfolder in `docs/user` and keep relevant documentation there. Each subfolder in the `user` folder must have its own `_sidebar.md` file with the links to the main module page and the list of docs it contains. diff --git a/docs/operator/README.md b/docs/operator/README.md new file mode 100644 index 0000000..ae0a1a7 --- /dev/null +++ b/docs/operator/README.md @@ -0,0 +1 @@ +This folder is mandatory only if your module/component is delivered to restricted markets.It includes documentation relevant for the respective operators. \ No newline at end of file diff --git a/docs/operator/cn/01-installation.md b/docs/operator/cn/01-installation.md new file mode 100644 index 0000000..026a832 --- /dev/null +++ b/docs/operator/cn/01-installation.md @@ -0,0 +1,15 @@ +# Installing {Component Name} + +## Prerequisites + + + +## Procedure + + + +## Post-Installation Steps + + + + \ No newline at end of file diff --git a/docs/operator/cn/02-update.md b/docs/operator/cn/02-update.md new file mode 100644 index 0000000..a3abcf0 --- /dev/null +++ b/docs/operator/cn/02-update.md @@ -0,0 +1,15 @@ +# Updating {Component Name} + +# Prerequisites + + + +## Procedure + + + +## Post-Update Stapes + + + + \ No newline at end of file diff --git a/docs/operator/cn/03-operations.md b/docs/operator/cn/03-operations.md new file mode 100644 index 0000000..931e2bf --- /dev/null +++ b/docs/operator/cn/03-operations.md @@ -0,0 +1,3 @@ +# {Component/Service Name} - Operations + + \ No newline at end of file diff --git a/docs/operator/cn/04-troubleshooting.md b/docs/operator/cn/04-troubleshooting.md new file mode 100644 index 0000000..387a056 --- /dev/null +++ b/docs/operator/cn/04-troubleshooting.md @@ -0,0 +1,8 @@ +# {Component/Service Name} - Troubleshooting + + + + diff --git a/docs/operator/cn/README.md b/docs/operator/cn/README.md new file mode 100644 index 0000000..c0ee109 --- /dev/null +++ b/docs/operator/cn/README.md @@ -0,0 +1,10 @@ +This folder includes documentation relevant for the China cloud operator. The documentation is published as part of the [SAP BTP, Partner-Managed Edition](https://help.sap.com/docs/CPOPS?state=DRAFT) official documentation in SAP Help Portal. + +The mandatory documentation types include: + +- Installation +- Update +- Operations +- Troubleshooting + +You will find the respective files for each of the documentation type in the template file structure. diff --git a/docs/operator/ns2/01-installation.md b/docs/operator/ns2/01-installation.md new file mode 100644 index 0000000..026a832 --- /dev/null +++ b/docs/operator/ns2/01-installation.md @@ -0,0 +1,15 @@ +# Installing {Component Name} + +## Prerequisites + + + +## Procedure + + + +## Post-Installation Steps + + + + \ No newline at end of file diff --git a/docs/operator/ns2/02-update.md b/docs/operator/ns2/02-update.md new file mode 100644 index 0000000..a3abcf0 --- /dev/null +++ b/docs/operator/ns2/02-update.md @@ -0,0 +1,15 @@ +# Updating {Component Name} + +# Prerequisites + + + +## Procedure + + + +## Post-Update Stapes + + + + \ No newline at end of file diff --git a/docs/operator/ns2/03-operations.md b/docs/operator/ns2/03-operations.md new file mode 100644 index 0000000..931e2bf --- /dev/null +++ b/docs/operator/ns2/03-operations.md @@ -0,0 +1,3 @@ +# {Component/Service Name} - Operations + + \ No newline at end of file diff --git a/docs/operator/ns2/04-troubleshooting.md b/docs/operator/ns2/04-troubleshooting.md new file mode 100644 index 0000000..387a056 --- /dev/null +++ b/docs/operator/ns2/04-troubleshooting.md @@ -0,0 +1,8 @@ +# {Component/Service Name} - Troubleshooting + + + + diff --git a/docs/operator/ns2/README.md b/docs/operator/ns2/README.md new file mode 100644 index 0000000..f08294f --- /dev/null +++ b/docs/operator/ns2/README.md @@ -0,0 +1,10 @@ +This folder includes documentation relevant for the NS2 operator. The documentation is published as part of the [SAP BTP, Partner-Managed Edition (AWS GovCloud)](https://help.sap.com/docs/OPSAWS?state=DRAFT) official documentation in SAP Help Portal. + +The mandatory documentation types include: + +- Installation +- Update +- Operations +- Troubleshooting + +You will find the respective files for each of the documentation type in the template file structure. From 51fbb5fab4f241b40191a3a416825cdfa3e3b4c1 Mon Sep 17 00:00:00 2001 From: mmitoraj Date: Wed, 23 Oct 2024 13:58:55 +0200 Subject: [PATCH 02/13] Adjust file names --- docs/operator/cn/{01-installation.md => 01-10-installation.md} | 0 docs/operator/cn/{02-update.md => 02-10-update.md} | 0 docs/operator/cn/{03-operations.md => 03-10-operations.md} | 0 .../cn/{04-troubleshooting.md => 04-10-troubleshooting.md} | 0 docs/operator/ns2/{01-installation.md => 01-10-installation.md} | 0 docs/operator/ns2/{02-update.md => 02-10-update.md} | 0 docs/operator/ns2/{03-operations.md => 03-10-operations.md} | 0 .../ns2/{04-troubleshooting.md => 04-10-troubleshooting.md} | 0 8 files changed, 0 insertions(+), 0 deletions(-) rename docs/operator/cn/{01-installation.md => 01-10-installation.md} (100%) rename docs/operator/cn/{02-update.md => 02-10-update.md} (100%) rename docs/operator/cn/{03-operations.md => 03-10-operations.md} (100%) rename docs/operator/cn/{04-troubleshooting.md => 04-10-troubleshooting.md} (100%) rename docs/operator/ns2/{01-installation.md => 01-10-installation.md} (100%) rename docs/operator/ns2/{02-update.md => 02-10-update.md} (100%) rename docs/operator/ns2/{03-operations.md => 03-10-operations.md} (100%) rename docs/operator/ns2/{04-troubleshooting.md => 04-10-troubleshooting.md} (100%) diff --git a/docs/operator/cn/01-installation.md b/docs/operator/cn/01-10-installation.md similarity index 100% rename from docs/operator/cn/01-installation.md rename to docs/operator/cn/01-10-installation.md diff --git a/docs/operator/cn/02-update.md b/docs/operator/cn/02-10-update.md similarity index 100% rename from docs/operator/cn/02-update.md rename to docs/operator/cn/02-10-update.md diff --git a/docs/operator/cn/03-operations.md b/docs/operator/cn/03-10-operations.md similarity index 100% rename from docs/operator/cn/03-operations.md rename to docs/operator/cn/03-10-operations.md diff --git a/docs/operator/cn/04-troubleshooting.md b/docs/operator/cn/04-10-troubleshooting.md similarity index 100% rename from docs/operator/cn/04-troubleshooting.md rename to docs/operator/cn/04-10-troubleshooting.md diff --git a/docs/operator/ns2/01-installation.md b/docs/operator/ns2/01-10-installation.md similarity index 100% rename from docs/operator/ns2/01-installation.md rename to docs/operator/ns2/01-10-installation.md diff --git a/docs/operator/ns2/02-update.md b/docs/operator/ns2/02-10-update.md similarity index 100% rename from docs/operator/ns2/02-update.md rename to docs/operator/ns2/02-10-update.md diff --git a/docs/operator/ns2/03-operations.md b/docs/operator/ns2/03-10-operations.md similarity index 100% rename from docs/operator/ns2/03-operations.md rename to docs/operator/ns2/03-10-operations.md diff --git a/docs/operator/ns2/04-troubleshooting.md b/docs/operator/ns2/04-10-troubleshooting.md similarity index 100% rename from docs/operator/ns2/04-troubleshooting.md rename to docs/operator/ns2/04-10-troubleshooting.md From d1da290170e9b85103d528ef2ff99d8e61b0a6d8 Mon Sep 17 00:00:00 2001 From: mmitoraj Date: Wed, 23 Oct 2024 15:56:38 +0200 Subject: [PATCH 03/13] Apply Iwona's suggestions --- docs/README.md | 4 ++-- docs/operator/README.md | 2 +- docs/operator/cn/01-10-installation.md | 4 ++-- docs/operator/cn/02-10-update.md | 4 ++-- docs/operator/cn/03-10-operations.md | 4 +++- docs/operator/cn/04-10-troubleshooting.md | 8 ++++---- docs/operator/cn/README.md | 4 ++-- docs/operator/ns2/01-10-installation.md | 4 ++-- docs/operator/ns2/02-10-update.md | 2 +- docs/operator/ns2/03-10-operations.md | 4 +++- docs/operator/ns2/04-10-troubleshooting.md | 6 +++--- docs/operator/ns2/README.md | 4 ++-- 12 files changed, 27 insertions(+), 23 deletions(-) diff --git a/docs/README.md b/docs/README.md index a3b3fec..2dd7b4c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,13 +2,13 @@ ## Overview -The `docs` folder contains three subfolders - `user`, `contributor` and `operator`. +The `docs` folder contains three subfolders - `user`, `contributor` and `operator`*. The `user` subfolder contains the end-user documentation, which is displayed on the [Kyma website](https://kyma-project.io/#/) and in the SAP Help Portal. Depending on your module needs, the subfolder must include overview, usage, or technical reference documents. To display the content on the website properly, create a `_sidebar.md` file in the `user` subfolder and list the documents it contains there. For more information on how to publish user documentation, follow [this guide](https://github.com/kyma-project/community/blob/main/docs/guidelines/content-guidelines/01-user-docs.md). The `contributor` subfolder includes any developer-related documentation to help them manually install, develop, and operate a module. -The `operator` subfolder is mandatory only if your module/component is delivered to restricted markets. The subfolder includes documentation relevant for the respective operators. +* The `operator` subfolder is mandatory only if your module/component is delivered to restricted markets. The subfolder includes documentation relevant to the respective operators. To have a common structure across all modules, all documents must be properly numbered according to the following structure: diff --git a/docs/operator/README.md b/docs/operator/README.md index ae0a1a7..35cd335 100644 --- a/docs/operator/README.md +++ b/docs/operator/README.md @@ -1 +1 @@ -This folder is mandatory only if your module/component is delivered to restricted markets.It includes documentation relevant for the respective operators. \ No newline at end of file +This folder is mandatory only if your module/component is delivered to restricted markets.It includes documentation relevant to the respective operators. \ No newline at end of file diff --git a/docs/operator/cn/01-10-installation.md b/docs/operator/cn/01-10-installation.md index 026a832..fa8d5ae 100644 --- a/docs/operator/cn/01-10-installation.md +++ b/docs/operator/cn/01-10-installation.md @@ -10,6 +10,6 @@ ## Post-Installation Steps - + - \ No newline at end of file + \ No newline at end of file diff --git a/docs/operator/cn/02-10-update.md b/docs/operator/cn/02-10-update.md index a3abcf0..c6c71cf 100644 --- a/docs/operator/cn/02-10-update.md +++ b/docs/operator/cn/02-10-update.md @@ -8,8 +8,8 @@ -## Post-Update Stapes +## Post-Update Steps - \ No newline at end of file + diff --git a/docs/operator/cn/03-10-operations.md b/docs/operator/cn/03-10-operations.md index 931e2bf..4dca380 100644 --- a/docs/operator/cn/03-10-operations.md +++ b/docs/operator/cn/03-10-operations.md @@ -1,3 +1,5 @@ # {Component/Service Name} - Operations - \ No newline at end of file + + + \ No newline at end of file diff --git a/docs/operator/cn/04-10-troubleshooting.md b/docs/operator/cn/04-10-troubleshooting.md index 387a056..0ef71f5 100644 --- a/docs/operator/cn/04-10-troubleshooting.md +++ b/docs/operator/cn/04-10-troubleshooting.md @@ -1,8 +1,8 @@ # {Component/Service Name} - Troubleshooting +- Use a problem-solution format, where a problem can be a statement or a question. +- If you have multiple solutions, provide the recommended solution first. +- Provide all recommended actions and introduce a connection to the alerts of your service, preferably the monitor name.--> - + diff --git a/docs/operator/cn/README.md b/docs/operator/cn/README.md index c0ee109..086fca7 100644 --- a/docs/operator/cn/README.md +++ b/docs/operator/cn/README.md @@ -1,4 +1,4 @@ -This folder includes documentation relevant for the China cloud operator. The documentation is published as part of the [SAP BTP, Partner-Managed Edition](https://help.sap.com/docs/CPOPS?state=DRAFT) official documentation in SAP Help Portal. +This folder includes documentation relevant to the China cloud operator. The documentation is published as part of the [SAP BTP, Partner-Managed Edition](https://help.sap.com/docs/CPOPS?state=DRAFT) official documentation in the SAP Help Portal. The mandatory documentation types include: @@ -7,4 +7,4 @@ The mandatory documentation types include: - Operations - Troubleshooting -You will find the respective files for each of the documentation type in the template file structure. +You will find the respective files for each documentation type in the template file structure. diff --git a/docs/operator/ns2/01-10-installation.md b/docs/operator/ns2/01-10-installation.md index 026a832..fa8d5ae 100644 --- a/docs/operator/ns2/01-10-installation.md +++ b/docs/operator/ns2/01-10-installation.md @@ -10,6 +10,6 @@ ## Post-Installation Steps - + - \ No newline at end of file + \ No newline at end of file diff --git a/docs/operator/ns2/02-10-update.md b/docs/operator/ns2/02-10-update.md index a3abcf0..50835d9 100644 --- a/docs/operator/ns2/02-10-update.md +++ b/docs/operator/ns2/02-10-update.md @@ -12,4 +12,4 @@ - \ No newline at end of file + \ No newline at end of file diff --git a/docs/operator/ns2/03-10-operations.md b/docs/operator/ns2/03-10-operations.md index 931e2bf..4dca380 100644 --- a/docs/operator/ns2/03-10-operations.md +++ b/docs/operator/ns2/03-10-operations.md @@ -1,3 +1,5 @@ # {Component/Service Name} - Operations - \ No newline at end of file + + + \ No newline at end of file diff --git a/docs/operator/ns2/04-10-troubleshooting.md b/docs/operator/ns2/04-10-troubleshooting.md index 387a056..f32d418 100644 --- a/docs/operator/ns2/04-10-troubleshooting.md +++ b/docs/operator/ns2/04-10-troubleshooting.md @@ -1,8 +1,8 @@ # {Component/Service Name} - Troubleshooting - + diff --git a/docs/operator/ns2/README.md b/docs/operator/ns2/README.md index f08294f..43b8aec 100644 --- a/docs/operator/ns2/README.md +++ b/docs/operator/ns2/README.md @@ -1,4 +1,4 @@ -This folder includes documentation relevant for the NS2 operator. The documentation is published as part of the [SAP BTP, Partner-Managed Edition (AWS GovCloud)](https://help.sap.com/docs/OPSAWS?state=DRAFT) official documentation in SAP Help Portal. +This folder includes documentation relevant for the NS2 operator. The documentation is published as part of the [SAP BTP, Partner-Managed Edition (AWS GovCloud)](https://help.sap.com/docs/OPSAWS?state=DRAFT) official documentation in the SAP Help Portal The mandatory documentation types include: @@ -7,4 +7,4 @@ The mandatory documentation types include: - Operations - Troubleshooting -You will find the respective files for each of the documentation type in the template file structure. +You will find the respective files for each documentation type in the template file structure. From a581db2a69a7bc3959eb4db2a027320eab497ac6 Mon Sep 17 00:00:00 2001 From: mmitoraj Date: Wed, 23 Oct 2024 16:02:16 +0200 Subject: [PATCH 04/13] Fix Typo --- docs/operator/ns2/02-10-update.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/operator/ns2/02-10-update.md b/docs/operator/ns2/02-10-update.md index 50835d9..42e71e7 100644 --- a/docs/operator/ns2/02-10-update.md +++ b/docs/operator/ns2/02-10-update.md @@ -8,7 +8,7 @@ -## Post-Update Stapes +## Post-Update Steps From 13cc51459500833a4b1103140a620a76d8d9a2fa Mon Sep 17 00:00:00 2001 From: mmitoraj Date: Wed, 23 Oct 2024 16:07:36 +0200 Subject: [PATCH 05/13] Formatting --- docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 2dd7b4c..574ea3e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,7 +2,7 @@ ## Overview -The `docs` folder contains three subfolders - `user`, `contributor` and `operator`*. +The `docs` folder contains three subfolders - `user`, `contributor`, and `operator`*. The `user` subfolder contains the end-user documentation, which is displayed on the [Kyma website](https://kyma-project.io/#/) and in the SAP Help Portal. Depending on your module needs, the subfolder must include overview, usage, or technical reference documents. To display the content on the website properly, create a `_sidebar.md` file in the `user` subfolder and list the documents it contains there. For more information on how to publish user documentation, follow [this guide](https://github.com/kyma-project/community/blob/main/docs/guidelines/content-guidelines/01-user-docs.md). From 10eb89c126e152029a5729a59317dfc57acfb841 Mon Sep 17 00:00:00 2001 From: mmitoraj Date: Wed, 23 Oct 2024 16:17:14 +0200 Subject: [PATCH 06/13] Fix formatting --- docs/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/README.md b/docs/README.md index 574ea3e..378044e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,13 +2,13 @@ ## Overview -The `docs` folder contains three subfolders - `user`, `contributor`, and `operator`*. +The `docs` folder contains three subfolders - `user`, `contributor`, and `operator`[*]. The `user` subfolder contains the end-user documentation, which is displayed on the [Kyma website](https://kyma-project.io/#/) and in the SAP Help Portal. Depending on your module needs, the subfolder must include overview, usage, or technical reference documents. To display the content on the website properly, create a `_sidebar.md` file in the `user` subfolder and list the documents it contains there. For more information on how to publish user documentation, follow [this guide](https://github.com/kyma-project/community/blob/main/docs/guidelines/content-guidelines/01-user-docs.md). The `contributor` subfolder includes any developer-related documentation to help them manually install, develop, and operate a module. -* The `operator` subfolder is mandatory only if your module/component is delivered to restricted markets. The subfolder includes documentation relevant to the respective operators. +[*]The `operator` subfolder is mandatory only if your module/component is delivered to restricted markets. The subfolder includes documentation relevant to the respective operators. To have a common structure across all modules, all documents must be properly numbered according to the following structure: From 0e51c69d36749b2101f85e2c917ab76eaa524d90 Mon Sep 17 00:00:00 2001 From: mmitoraj Date: Wed, 23 Oct 2024 16:23:22 +0200 Subject: [PATCH 07/13] Use footnote --- docs/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/README.md b/docs/README.md index 378044e..c64f1e2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,13 +2,13 @@ ## Overview -The `docs` folder contains three subfolders - `user`, `contributor`, and `operator`[*]. +The `docs` folder contains three subfolders - `user`, `contributor`, and `operator`[^*]. The `user` subfolder contains the end-user documentation, which is displayed on the [Kyma website](https://kyma-project.io/#/) and in the SAP Help Portal. Depending on your module needs, the subfolder must include overview, usage, or technical reference documents. To display the content on the website properly, create a `_sidebar.md` file in the `user` subfolder and list the documents it contains there. For more information on how to publish user documentation, follow [this guide](https://github.com/kyma-project/community/blob/main/docs/guidelines/content-guidelines/01-user-docs.md). The `contributor` subfolder includes any developer-related documentation to help them manually install, develop, and operate a module. -[*]The `operator` subfolder is mandatory only if your module/component is delivered to restricted markets. The subfolder includes documentation relevant to the respective operators. +[^*] The `operator`* subfolder is mandatory only if your module/component is delivered to restricted markets. The subfolder includes documentation relevant to the respective operators. To have a common structure across all modules, all documents must be properly numbered according to the following structure: From c09424fafe9ac0234cd9971a43095db90f946408 Mon Sep 17 00:00:00 2001 From: mmitoraj Date: Wed, 23 Oct 2024 16:25:49 +0200 Subject: [PATCH 08/13] Fix footnote --- docs/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/README.md b/docs/README.md index c64f1e2..3e08d9d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,13 +2,13 @@ ## Overview -The `docs` folder contains three subfolders - `user`, `contributor`, and `operator`[^*]. +The `docs` folder contains three subfolders - `user`, `contributor`, and `operator`[^1]. The `user` subfolder contains the end-user documentation, which is displayed on the [Kyma website](https://kyma-project.io/#/) and in the SAP Help Portal. Depending on your module needs, the subfolder must include overview, usage, or technical reference documents. To display the content on the website properly, create a `_sidebar.md` file in the `user` subfolder and list the documents it contains there. For more information on how to publish user documentation, follow [this guide](https://github.com/kyma-project/community/blob/main/docs/guidelines/content-guidelines/01-user-docs.md). The `contributor` subfolder includes any developer-related documentation to help them manually install, develop, and operate a module. -[^*] The `operator`* subfolder is mandatory only if your module/component is delivered to restricted markets. The subfolder includes documentation relevant to the respective operators. +[^1] The `operator`* subfolder is mandatory only if your module/component is delivered to restricted markets. The subfolder includes documentation relevant to the respective operators. To have a common structure across all modules, all documents must be properly numbered according to the following structure: From 91dfb498ecdffbd7ff27461ea69096b98ec4c277 Mon Sep 17 00:00:00 2001 From: mmitoraj Date: Wed, 23 Oct 2024 16:28:07 +0200 Subject: [PATCH 09/13] fix footnote --- docs/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/README.md b/docs/README.md index 3e08d9d..705e574 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,13 +2,13 @@ ## Overview -The `docs` folder contains three subfolders - `user`, `contributor`, and `operator`[^1]. +The `docs` folder contains three subfolders - `user`, `contributor`, and `operator`[^*]. The `user` subfolder contains the end-user documentation, which is displayed on the [Kyma website](https://kyma-project.io/#/) and in the SAP Help Portal. Depending on your module needs, the subfolder must include overview, usage, or technical reference documents. To display the content on the website properly, create a `_sidebar.md` file in the `user` subfolder and list the documents it contains there. For more information on how to publish user documentation, follow [this guide](https://github.com/kyma-project/community/blob/main/docs/guidelines/content-guidelines/01-user-docs.md). The `contributor` subfolder includes any developer-related documentation to help them manually install, develop, and operate a module. -[^1] The `operator`* subfolder is mandatory only if your module/component is delivered to restricted markets. The subfolder includes documentation relevant to the respective operators. +[^*]: The `operator` subfolder is mandatory only if your module/component is delivered to restricted markets. The subfolder includes documentation relevant to the respective operators. To have a common structure across all modules, all documents must be properly numbered according to the following structure: From 3b1fc2b5915dba32ac9129eeb261d77046e0436c Mon Sep 17 00:00:00 2001 From: mmitoraj Date: Wed, 23 Oct 2024 16:41:30 +0200 Subject: [PATCH 10/13] Update the footnote --- docs/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 705e574..aced087 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,7 +8,7 @@ The `user` subfolder contains the end-user documentation, which is displayed on The `contributor` subfolder includes any developer-related documentation to help them manually install, develop, and operate a module. -[^*]: The `operator` subfolder is mandatory only if your module/component is delivered to restricted markets. The subfolder includes documentation relevant to the respective operators. +The `operator` subfolder is mandatory only if your module/component is delivered to restricted markets. The subfolder includes documentation relevant to the respective operators. To have a common structure across all modules, all documents must be properly numbered according to the following structure: @@ -40,3 +40,5 @@ where `xx` is the number of the given document. For example: If you have other content that does not fit into the above topics, create your own 04-10-module-specific document(s). You can divide your documentation into subfolders to avoid having too many documents in one `docs/user` or `docs/contributor` folder. For example, if you have many technical reference documents, you can create a `technical reference` subfolder in `docs/user` and keep relevant documentation there. Each subfolder in the `user` folder must have its own `_sidebar.md` file with the links to the main module page and the list of docs it contains. + +[^*]: Only in documentation for restricted markets. From edcefba74a63a4060a4cb7eaeded2c1b79af9f90 Mon Sep 17 00:00:00 2001 From: mmitoraj Date: Thu, 24 Oct 2024 09:14:58 +0200 Subject: [PATCH 11/13] Apply review suggestions --- docs/operator/README.md | 2 +- docs/operator/cn/01-10-installation.md | 4 +++- docs/operator/cn/03-10-operations.md | 14 +++++++++++++- docs/operator/ns2/01-10-installation.md | 4 +++- docs/operator/ns2/03-10-operations.md | 14 +++++++++++++- docs/operator/ns2/04-10-troubleshooting.md | 2 +- docs/operator/ns2/README.md | 2 +- 7 files changed, 35 insertions(+), 7 deletions(-) diff --git a/docs/operator/README.md b/docs/operator/README.md index 35cd335..d5f98a3 100644 --- a/docs/operator/README.md +++ b/docs/operator/README.md @@ -1 +1 @@ -This folder is mandatory only if your module/component is delivered to restricted markets.It includes documentation relevant to the respective operators. \ No newline at end of file +This folder is mandatory only if your module/component is delivered to restricted markets. It includes documentation relevant to the respective operators. \ No newline at end of file diff --git a/docs/operator/cn/01-10-installation.md b/docs/operator/cn/01-10-installation.md index fa8d5ae..5216984 100644 --- a/docs/operator/cn/01-10-installation.md +++ b/docs/operator/cn/01-10-installation.md @@ -2,7 +2,9 @@ ## Prerequisites - + ## Procedure diff --git a/docs/operator/cn/03-10-operations.md b/docs/operator/cn/03-10-operations.md index 4dca380..74efcb6 100644 --- a/docs/operator/cn/03-10-operations.md +++ b/docs/operator/cn/03-10-operations.md @@ -1,5 +1,17 @@ # {Component/Service Name} - Operations - + + + \ No newline at end of file diff --git a/docs/operator/ns2/01-10-installation.md b/docs/operator/ns2/01-10-installation.md index fa8d5ae..5216984 100644 --- a/docs/operator/ns2/01-10-installation.md +++ b/docs/operator/ns2/01-10-installation.md @@ -2,7 +2,9 @@ ## Prerequisites - + ## Procedure diff --git a/docs/operator/ns2/03-10-operations.md b/docs/operator/ns2/03-10-operations.md index 4dca380..74efcb6 100644 --- a/docs/operator/ns2/03-10-operations.md +++ b/docs/operator/ns2/03-10-operations.md @@ -1,5 +1,17 @@ # {Component/Service Name} - Operations - + + + \ No newline at end of file diff --git a/docs/operator/ns2/04-10-troubleshooting.md b/docs/operator/ns2/04-10-troubleshooting.md index f32d418..b01811e 100644 --- a/docs/operator/ns2/04-10-troubleshooting.md +++ b/docs/operator/ns2/04-10-troubleshooting.md @@ -3,6 +3,6 @@ +- Provide all recommended actions and introduce a connection to the alerts of your service, preferably the monitor name.--> diff --git a/docs/operator/ns2/README.md b/docs/operator/ns2/README.md index 43b8aec..ef39595 100644 --- a/docs/operator/ns2/README.md +++ b/docs/operator/ns2/README.md @@ -1,4 +1,4 @@ -This folder includes documentation relevant for the NS2 operator. The documentation is published as part of the [SAP BTP, Partner-Managed Edition (AWS GovCloud)](https://help.sap.com/docs/OPSAWS?state=DRAFT) official documentation in the SAP Help Portal +This folder includes documentation relevant to the NS2 operator. The documentation is published as part of the [SAP BTP, Partner-Managed Edition (AWS GovCloud)](https://help.sap.com/docs/OPSAWS?state=DRAFT) official documentation in the SAP Help Portal The mandatory documentation types include: From ef972c2a35414960fd8f8a3bb4e5cae960b448dd Mon Sep 17 00:00:00 2001 From: mmitoraj Date: Thu, 24 Oct 2024 10:04:25 +0200 Subject: [PATCH 12/13] Apply suggestions from review --- docs/operator/cn/02-10-update.md | 11 ++++++++++- docs/operator/cn/03-10-operations.md | 5 +++++ docs/operator/ns2/02-10-update.md | 11 ++++++++++- docs/operator/ns2/03-10-operations.md | 5 +++++ 4 files changed, 30 insertions(+), 2 deletions(-) diff --git a/docs/operator/cn/02-10-update.md b/docs/operator/cn/02-10-update.md index c6c71cf..e0e8359 100644 --- a/docs/operator/cn/02-10-update.md +++ b/docs/operator/cn/02-10-update.md @@ -1,9 +1,18 @@ # Updating {Component Name} -# Prerequisites +## Prerequisites +## What's Changed {OPTIONAL} + + + ## Procedure diff --git a/docs/operator/cn/03-10-operations.md b/docs/operator/cn/03-10-operations.md index 74efcb6..4ba1f07 100644 --- a/docs/operator/cn/03-10-operations.md +++ b/docs/operator/cn/03-10-operations.md @@ -3,6 +3,11 @@ +## What's Changed {OPTIONAL} + + + ## Procedure diff --git a/docs/operator/ns2/03-10-operations.md b/docs/operator/ns2/03-10-operations.md index 74efcb6..4ba1f07 100644 --- a/docs/operator/ns2/03-10-operations.md +++ b/docs/operator/ns2/03-10-operations.md @@ -3,6 +3,11 @@ +- CRs' labels and annotations + +## Metrics + +In this section describe: +- What metrics endpoints does the component use? What is the metrics format? (Prometheus is expected) +- What metrics are presented on each endpoint? Describe all the metrics and what they represent. +- Provide the recommended way to determine warnings and identify critical values in metrics. + +Consider describing some recommendations regarding conditions and thresholds for triggering alerts. + +--> \ No newline at end of file diff --git a/docs/operator/ns2/03-10-operations.md b/docs/operator/ns2/03-10-operations.md index 4ba1f07..bcf8d74 100644 --- a/docs/operator/ns2/03-10-operations.md +++ b/docs/operator/ns2/03-10-operations.md @@ -17,6 +17,16 @@ In this section, describe: - The component's CRs and their purpose - CRs' backup requirements (Is it regenerated or does it require backup?) - CRs' mechanics -- CRs' labels and annotations --> +- CRs' labels and annotations + +## Metrics + +In this section describe: +- What metrics endpoints does the component use? What is the metrics format? (Prometheus is expected) +- What metrics are presented on each endpoint? Describe all the metrics and what they represent. +- Provide the recommended way to determine warnings and identify critical values in metrics. + +Consider describing some recommendations regarding conditions and thresholds for triggering alerts. +--> \ No newline at end of file diff --git a/docs/operator/ns2/README.md b/docs/operator/ns2/README.md index ef39595..2b55337 100644 --- a/docs/operator/ns2/README.md +++ b/docs/operator/ns2/README.md @@ -1,4 +1,4 @@ -This folder includes documentation relevant to the NS2 operator. The documentation is published as part of the [SAP BTP, Partner-Managed Edition (AWS GovCloud)](https://help.sap.com/docs/OPSAWS?state=DRAFT) official documentation in the SAP Help Portal +This folder includes documentation relevant to the NS2 operator. The documentation is published as part of the [SAP BTP, Partner-Managed Edition (AWS GovCloud)](https://help.sap.com/docs/OPSAWS?state=DRAFT) official documentation in the SAP Help Portal. The mandatory documentation types include: