diff --git a/docs/README.md b/docs/README.md index 84aca7b..aced087 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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. @@ -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. \ No newline at end of file +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. diff --git a/docs/operator/README.md b/docs/operator/README.md new file mode 100644 index 0000000..7a6a8ec --- /dev/null +++ b/docs/operator/README.md @@ -0,0 +1,7 @@ +This folder is mandatory only if your module/component is delivered to restricted markets. It includes documentation relevant to the respective operators. + +## General Guidelines + +Our target persona has a good knowledge of the technical concepts involved, and does not need a detailed breakdown of steps at the click-level. If there are complicated procedures, use your judgment to break it into steps for easy consumption. + +Although the target persona has the technical knowledge, they don't know Kyma specifics. Explain all the Kyma-related concepts and steps thoroughly with attention to details and understanding for the target user perspective. diff --git a/docs/operator/cn/01-10-installation.md b/docs/operator/cn/01-10-installation.md new file mode 100644 index 0000000..5216984 --- /dev/null +++ b/docs/operator/cn/01-10-installation.md @@ -0,0 +1,17 @@ +# Installing {Component Name} + +## Prerequisites + + + +## Procedure + + + +## Post-Installation Steps + + + + \ No newline at end of file diff --git a/docs/operator/cn/02-10-update.md b/docs/operator/cn/02-10-update.md new file mode 100644 index 0000000..e0e8359 --- /dev/null +++ b/docs/operator/cn/02-10-update.md @@ -0,0 +1,24 @@ +# Updating {Component Name} + +## Prerequisites + + + +## What's Changed {OPTIONAL} + + + +## Procedure + + + +## Post-Update Steps + + + + diff --git a/docs/operator/cn/03-10-operations.md b/docs/operator/cn/03-10-operations.md new file mode 100644 index 0000000..e020e4e --- /dev/null +++ b/docs/operator/cn/03-10-operations.md @@ -0,0 +1,33 @@ +# {Component/Service Name} - Operations + + + + + + \ No newline at end of file diff --git a/docs/operator/cn/04-10-troubleshooting.md b/docs/operator/cn/04-10-troubleshooting.md new file mode 100644 index 0000000..0ef71f5 --- /dev/null +++ b/docs/operator/cn/04-10-troubleshooting.md @@ -0,0 +1,8 @@ +# {Component/Service Name} - Troubleshooting + + + + diff --git a/docs/operator/cn/README.md b/docs/operator/cn/README.md new file mode 100644 index 0000000..086fca7 --- /dev/null +++ b/docs/operator/cn/README.md @@ -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. diff --git a/docs/operator/ns2/01-10-installation.md b/docs/operator/ns2/01-10-installation.md new file mode 100644 index 0000000..5216984 --- /dev/null +++ b/docs/operator/ns2/01-10-installation.md @@ -0,0 +1,17 @@ +# Installing {Component Name} + +## Prerequisites + + + +## Procedure + + + +## Post-Installation Steps + + + + \ No newline at end of file diff --git a/docs/operator/ns2/02-10-update.md b/docs/operator/ns2/02-10-update.md new file mode 100644 index 0000000..712cbd2 --- /dev/null +++ b/docs/operator/ns2/02-10-update.md @@ -0,0 +1,24 @@ +# Updating {Component Name} + +## Prerequisites + + + +## What's Changed {OPTIONAL} + + + +## Procedure + + + +## Post-Update Steps + + + + \ No newline at end of file diff --git a/docs/operator/ns2/03-10-operations.md b/docs/operator/ns2/03-10-operations.md new file mode 100644 index 0000000..bcf8d74 --- /dev/null +++ b/docs/operator/ns2/03-10-operations.md @@ -0,0 +1,32 @@ +# {Component/Service Name} - Operations + + + + + + \ No newline at end of file diff --git a/docs/operator/ns2/04-10-troubleshooting.md b/docs/operator/ns2/04-10-troubleshooting.md new file mode 100644 index 0000000..b01811e --- /dev/null +++ b/docs/operator/ns2/04-10-troubleshooting.md @@ -0,0 +1,8 @@ +# {Component/Service Name} - Troubleshooting + + + + diff --git a/docs/operator/ns2/README.md b/docs/operator/ns2/README.md new file mode 100644 index 0000000..2b55337 --- /dev/null +++ b/docs/operator/ns2/README.md @@ -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.