Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add the operator folder to the template #44

Merged
merged 13 commits into from
Oct 24, 2024
13 changes: 9 additions & 4 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 to 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.
Expand All @@ -32,8 +34,11 @@ 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.
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.
1 change: 1 addition & 0 deletions docs/operator/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
This folder is mandatory only if your module/component is delivered to restricted markets. It includes documentation relevant to the respective operators.
17 changes: 17 additions & 0 deletions docs/operator/cn/01-10-installation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Installing {Component Name}

## Prerequisites

<!--Describe the prerequisites for installing your service (if there are some). For example:
- List the components that your component depends on
- List the BTP integrations used by your component-->

## Procedure

<!--Describe the installation steps in a logical sequence.-->

## Post-Installation Steps

<!--Describe any post-installation steps that you might need, including the initial setup of your monitors. Setting up monitors should also be part of your operations topic. However, please include this information here as well.-->

<!--For more information, see [Documentation Guidelines for Operator Documentation](https://wiki.one.int.sap/wiki/display/NDW/Documentation+Guidelines+for+Operator+Documentation#DocumentationGuidelinesforOperatorDocumentation-InstallationandUpdate)-->
24 changes: 24 additions & 0 deletions docs/operator/cn/02-10-update.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Updating {Component Name}
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should have a section for significant changes since the last release, depending on the release type. For patch updates, nothing is expected. For minor or major releases breaking changes are expected to be explained here.

This includes, but not limited to:

  • Mechanics changes (something worked X way, now works Y way)
  • New functionalities
  • Obsolete functionalities
  • Configuration changes
  • Updating pitfalls

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I understood it differently. For me, this document is about the update procedure that is more or less stable. It includes the steps to update the component. What you are describing sounds more like a changelog or a release note. We can re-confirm with Aneta. BTW, Aneta, do we also provide what's new notes for the partner-managed edition?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aneta confirmed that "it's actually both the stable steps but also the specific for the concrete version update. As an example, you can have a look at the BAS update documentation:
https://help.sap.com/docs/OPSAWS/a57e20d1d0124a5db7cf6b68a4b60c06/51a431e8a20841e5a3c258bda526ac10.html?state=DRAFT". Also, in addition, we probably will also publish What's New.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I proposed a section called "What's Changed". PTAL.


## Prerequisites

<!--Describe the prerequisites for updating your service (if there are some).-->

## What's Changed {OPTIONAL}

<!--In this optional section, describe significat changes since the last minor or major release. For example:
- Operation changes
- New functionalities
- Deprecated functionalities
- Configuration changes
- Updating pitfalls-->

## Procedure

<!--Describe the update steps in a logical sequence.-->

## Post-Update Steps

<!--Describe any post-update steps that you might need. If monitors need to be recreated after an update, add this information to the update structure of your service/component.-->

<!--For more information, see [Documentation Guidelines for Operator Documentation](https://wiki.one.int.sap/wiki/display/NDW/Documentation+Guidelines+for+Operator+Documentation#DocumentationGuidelinesforOperatorDocumentation-InstallationandUpdate)-->
22 changes: 22 additions & 0 deletions docs/operator/cn/03-10-operations.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# {Component/Service Name} - Operations

<!--Please create only one single document with multiple sections for your Operations documentation. Our goal is to display all Operations content for a service on a single page so that the operators can quickly search for information using the search function.-->

<!--Recommended sections:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One more section came to my mind we need to add here: Metrics

Each module and component needs to document the followings:

  • What metrics endpoints are there, and in what format they are producing metrics (prometheus is expected here generally)
  • What metrics are presented on each endpoint, and each and every of these need sufficient documentation for the reader to understand what kind of internal mechanics it is representing
  • Suggested way to determine warnings and critical levels for metrics

Separately for alerting, if some important conditions are represented by a combination of metrics, then these should also be listed as suggested alerts, along with threshold mechanics.

## Configuration

Desribe Helm charts parameters and configuration values used during installation.

Provide details on any injected configuration that the component expects. For example, ConfigMaps and/or Secrets.

## REST API {if applicable}

## Custom Resources

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 -->

<!--For more information, see [Documentation Guidelines for Operator Documentation](https://wiki.one.int.sap/wiki/display/NDW/Documentation+Guidelines+for+Operator+Documentation#DocumentationGuidelinesforOperatorDocumentation-OperationsDocumentation)-->
8 changes: 8 additions & 0 deletions docs/operator/cn/04-10-troubleshooting.md
Original file line number Diff line number Diff line change
@@ -0,0 +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.-->

<!--For more information, see [Documentation Guidelines for Troubleshooting Documentation](https://wiki.one.int.sap/wiki/display/NDW/Documentation+Guidelines+for+Operator+Documentation#DocumentationGuidelinesforOperatorDocumentation-TroubleshootingDocumentation)-->
10 changes: 10 additions & 0 deletions docs/operator/cn/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
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:

- Installation
- Update
- Operations
- Troubleshooting

You will find the respective files for each documentation type in the template file structure.
17 changes: 17 additions & 0 deletions docs/operator/ns2/01-10-installation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Installing {Component Name}

## Prerequisites

<!--Describe the prerequisites for installing your service (if there are some). For example:
- List the components that your component depends on
- List the BTP integrations used by your component-->

## Procedure

<!--Describe the installation steps in a logical sequence.-->

## Post-Installation Steps

<!--Describe any post-installation steps that you might need, including the initial setup of your monitors. Setting up monitors should also be part of your operations topic. However, please include this information here as well.-->

<!--For more information, see [Documentation Guidelines for Operator Documentation](https://wiki.one.int.sap/wiki/display/NDW/Documentation+Guidelines+for+Operator+Documentation#DocumentationGuidelinesforOperatorDocumentation-InstallationandUpdate)-->
24 changes: 24 additions & 0 deletions docs/operator/ns2/02-10-update.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Updating {Component Name}

## Prerequisites

<!--Describe the prerequisites for updating your service (if there are some).-->

## What's Changed {OPTIONAL}

<!--In this optional section, describe significat changes since the last minor or major release. For example:
- Operation changes
- New functionalities
- Deprecated functionalities
- Configuration changes
- Updating pitfalls-->

## Procedure

<!--Describe the update steps in a logical sequence.-->

## Post-Update Steps

<!--Describe any post-update steps that you might need. If monitors need to be recreated after an update, add this information to the update structure of your service/component.-->

<!--For more information, see [Documentation Guidelines for Operator Documentation](https://wiki.one.int.sap/wiki/display/NDW/Documentation+Guidelines+for+Operator+Documentation#DocumentationGuidelinesforOperatorDocumentation-InstallationandUpdate)-->
22 changes: 22 additions & 0 deletions docs/operator/ns2/03-10-operations.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# {Component/Service Name} - Operations

<!--Please create only one single document with multiple sections for your Operations documentation. Our goal is to display all Operations content for a service on a single page so that the operators can quickly search for information using the search function.-->

<!--Recommended sections:
## Configuration

Desribe Helm charts parameters and configuration values used during installation.

Provide details on any injected configuration that the component expects. For example, ConfigMaps and/or Secrets.

## REST API {if applicable}

## Custom Resources

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 -->

<!--For more information, see [Documentation Guidelines for Operator Documentation](https://wiki.one.int.sap/wiki/display/NDW/Documentation+Guidelines+for+Operator+Documentation#DocumentationGuidelinesforOperatorDocumentation-OperationsDocumentation)-->
8 changes: 8 additions & 0 deletions docs/operator/ns2/04-10-troubleshooting.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# {Component/Service Name} - Troubleshooting

<!--
- Use a problem-solution format, where a problem can be presented as 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.-->

<!--For more information, see [Documentation Guidelines for Troubleshooting Documentation](https://wiki.one.int.sap/wiki/display/NDW/Documentation+Guidelines+for+Operator+Documentation#DocumentationGuidelinesforOperatorDocumentation-TroubleshootingDocumentation)-->
10 changes: 10 additions & 0 deletions docs/operator/ns2/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
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:

- Installation
- Update
- Operations
- Troubleshooting

You will find the respective files for each documentation type in the template file structure.
Loading