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.
IwonaLanger marked this conversation as resolved.
Show resolved Hide resolved
15 changes: 15 additions & 0 deletions docs/operator/cn/01-10-installation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Installing {Component Name}

## Prerequisites

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

Choose a reason for hiding this comment

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

The following details are expected to present heres:

  • [components] What other components does this one depend on
  • What BTP integrations does this service is using/building upon


## 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)-->
15 changes: 15 additions & 0 deletions docs/operator/cn/02-10-update.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# 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).-->

## 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)-->
5 changes: 5 additions & 0 deletions docs/operator/cn/03-10-operations.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# {Component/Service Name} - Operations

<!--Please create only one single document 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.-->
Copy link

Choose a reason for hiding this comment

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

Disagree for components, this needs multiple sections.

I would suggest the following section for components:

  • REST API references (if the component has one)
  • Custom Resource documentation:
    • What is the purpose of which CR.
    • Backup requirements of the CR (regenerated or needs to be backed up)
    • The mechanics of the CR (eg for Kymas, spec syncs from SKR to KCP, while status is the other way around)
    • how to interface with them (if annotations/labels are triggering mechanics enumerate and document these)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

True, this document can or even must have multiple sections. Having them all in one file is important to make the search functionality easier.

I also included the sections you recommended. Thanks!


<!--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.
15 changes: 15 additions & 0 deletions docs/operator/ns2/01-10-installation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Installing {Component Name}

## Prerequisites

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

## 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)-->
15 changes: 15 additions & 0 deletions docs/operator/ns2/02-10-update.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Updating {Component Name}

# Prerequisites

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

## 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)-->
5 changes: 5 additions & 0 deletions docs/operator/ns2/03-10-operations.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# {Component/Service Name} - Operations

<!--Please create only one single document 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.-->

<!--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.-->
IwonaLanger marked this conversation as resolved.
Show resolved Hide resolved

<!--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 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
IwonaLanger marked this conversation as resolved.
Show resolved Hide resolved

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