Skip to content

Commit

Permalink
Add the operator folder to the template
Browse files Browse the repository at this point in the history
  • Loading branch information
mmitoraj committed Oct 22, 2024
1 parent 19eab7f commit 9832fba
Show file tree
Hide file tree
Showing 12 changed files with 110 additions and 4 deletions.
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`.

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

<!--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-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/cn/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)-->
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

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

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

<!--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-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-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-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/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.

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.

0 comments on commit 9832fba

Please sign in to comment.