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
11 changes: 7 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`.
IwonaLanger marked this conversation as resolved.
Show resolved Hide resolved

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

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,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.
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.
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 for 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 (ideally you can create referable content).-->

<!--For more information, see [Documentation Guidelines for Operator Documentation](https://wiki.one.int.sap/wiki/display/NDW/Documentation+Guidelines+for+Operator+Documentation)-->
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 Stapes

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

<!--For more information, see [Documentation Guidelines for Operator Documentation](https://wiki.one.int.sap/wiki/display/NDW/Documentation+Guidelines+for+Operator+Documentation)-->
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, whereas a problem can be a statement or a question. \
- If you have more than one solution, provide the recommended solution first. If you're not sure, add both.
- 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 Operator Documentation](https://wiki.one.int.sap/wiki/display/NDW/Documentation+Guidelines+for+Operator+Documentation)-->
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 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.
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 of the documentation type in the template file structure.
IwonaLanger marked this conversation as resolved.
Show resolved Hide resolved
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 (ideally you can create referable content).-->

<!--For more information, see [Documentation Guidelines for Operator Documentation](https://wiki.one.int.sap/wiki/display/NDW/Documentation+Guidelines+for+Operator+Documentation)-->
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 Stapes

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

<!--For more information, see [Documentation Guidelines for Operator Documentation](https://wiki.one.int.sap/wiki/display/NDW/Documentation+Guidelines+for+Operator+Documentation)-->
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, whereas a problem can be a statement or a question. \
- If you have more than one solution, provide the recommended solution first. If you're not sure, add both.
- 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 Operator Documentation](https://wiki.one.int.sap/wiki/display/NDW/Documentation+Guidelines+for+Operator+Documentation)-->
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 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 of the documentation type in the template file structure.
IwonaLanger marked this conversation as resolved.
Show resolved Hide resolved
Loading