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-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).-->
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)-->
IwonaLanger marked this conversation as resolved.
Show resolved Hide resolved
15 changes: 15 additions & 0 deletions docs/operator/cn/02-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
IwonaLanger marked this conversation as resolved.
Show resolved Hide resolved

<!--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)-->
IwonaLanger marked this conversation as resolved.
Show resolved Hide resolved
3 changes: 3 additions & 0 deletions docs/operator/cn/03-operations.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# {Component/Service Name} - Operations
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)-->
IwonaLanger marked this conversation as resolved.
Show resolved Hide resolved
8 changes: 8 additions & 0 deletions docs/operator/cn/04-troubleshooting.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# {Component/Service Name} - Troubleshooting

Copy link
Contributor

@IwonaLanger IwonaLanger Oct 23, 2024

Choose a reason for hiding this comment

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

Again, is it supposed to be just one doc? If so, should we add the information here?

<!--
- 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.
IwonaLanger marked this conversation as resolved.
Show resolved Hide resolved
- 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)-->
IwonaLanger marked this conversation as resolved.
Show resolved Hide resolved
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-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).-->
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)-->
IwonaLanger marked this conversation as resolved.
Show resolved Hide resolved
15 changes: 15 additions & 0 deletions docs/operator/ns2/02-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)-->
IwonaLanger marked this conversation as resolved.
Show resolved Hide resolved
3 changes: 3 additions & 0 deletions docs/operator/ns2/03-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)-->
IwonaLanger marked this conversation as resolved.
Show resolved Hide resolved
8 changes: 8 additions & 0 deletions docs/operator/ns2/04-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)-->
IwonaLanger marked this conversation as resolved.
Show resolved Hide resolved
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