Iterate on the feedback from TECH call

## Getting Started

Please check the relevant document at [documenting.md](doc/contribute/documenting.md).

## How does it work?

There are 2 ways to upgrade documentation published on the [OSL Documentation] website:

  * Push any change on **develop** branch will force update of the **develop** version on the [OSL Documentation] website;

  * Create a tag, this will create a version with the tag name on the [OSL Documentation] website.

### Branches

This documentation repository has 2 protected branches:

  * **main**: stable timeline on which tags are made;

  * **develop**: edge timeline, also published on the [OSL Documentation] website.

### Structure

In the `mkdocs.yml` file you will find the navigation structure of the documentation, there you can sections with sub-sections.

*For example:*

```yaml

nav:

  - Overview:

    - Introduction: index.md

    - Deployment examples: deployment_examples.md

    - History: history.md

    - OpenSlice under ETSI: etsi_osl.md

  - Getting Started:

    - Deployment: 

      - Introduction: ./getting_started/deployment/introduction.md

      - Docker Compose: ./getting_started/deployment/docker_compose.md

      - Kubernetes: ./getting_started/deployment/kubernetes.md

    - Portals: ./getting_started/portals.md

[...]

```

Please take a moment to understand the current structure of the documentations and think to update after contributing if necessary.

### Main Page

The page shown first is at **doc/index.md**. That page should be updated with the latest changes of OpenSlice and should reference the version (useful shortcut is ``{{{ documentation_version }}}``).

[MkDocs](https://www.mkdocs.org/) is a fast and simple static site generator that's geared towards building project documentation. Documentation source files are written in `Markdown`, and configured with a single `YAML` configuration file. Start by reading the [introductory tutorial](https://www.mkdocs.org/getting-started/), then check the [User Guide](https://www.mkdocs.org/user-guide/) for more information.

### How does it work?

There are 2 ways to upgrade documentation published on the [OSL Documentation] website:

  * Push any change on **develop** branch will force update of the **develop** version on the [OSL Documentation] website;

  * Create a tag, this will create a version with the tag name on the [OSL Documentation] website.

### Branches

This documentation repository has 2 protected branches:

  * **main**: stable timeline on which tags are made;

  * **develop**: edge timeline, also published on the [OSL Documentation] website.

### Structure

In the `mkdocs.yml` file you will find the navigation structure of the documentation, there you can sections with sub-sections.

*For example:*

```yaml

nav:

  - Overview:

    - Introduction: index.md

    - Deployment examples: deployment_examples.md

    - History: history.md

    - OpenSlice under ETSI: etsi_osl.md

  - Getting Started:

    - Deployment: 

      - Introduction: ./getting_started/deployment/introduction.md

      - Docker Compose: ./getting_started/deployment/docker_compose.md

      - Kubernetes: ./getting_started/deployment/kubernetes.md

    - Portals: ./getting_started/portals.md

[...]

```

Please take a moment to understand the current structure of the documentations and think to update after contributing if necessary.

### Main Page

The page shown first is at **doc/index.md**. That page should be updated with the latest changes of OpenSlice and should reference the version (useful shortcut is ``{{{ documentation_version }}}``).

## Getting Started

To contribute to OpenSlice's documentation, you need to follow these easy steps:

1) Clone the [Documentation repository](https://labs.etsi.org/rep/osl/documentation) with:

```bash

git clone https://labs.etsi.org/rep/ocf/documentation.git

git clone https://labs.etsi.org/rep/osl/documentation.git

```

2) Checkout the develop branch (incoming contributions are only accepted to the **develop** branch):

git checkout develop

```

3) Setup a virtual environment:

3) Setup a local ``mkdocs`` server with a virtual environment:

* On Linux/macOS:

=== "Linux + macOS"

    ``` bash

python3 -m venv venv # Linux/macOS

source venv/bin/activate #Linux/macOS

    python3 -m venv venv

    source venv/bin/activate

    ```

* On Windows:

=== "Windows"

    ``` bash

python -m venv venv # Windows

venv\Scripts\activate # Windows

    python -m venv venv

    venv\Scripts\activate

    ```

4) Setup a local ``mkdocs`` server by installing requirements:

``` bash

python -m pip install -r requirements.txt

```

[OSL Web]: https://osl.etsi.org/ "OSL Web"

[OSL Documentation]: https://osl.etsi.org/documentation/ "OSL Documentation"

##  Learn more

If you wish to learn more about the documentation system, check [this](https://labs.etsi.org/rep/osl/documentation/README.md) link.

 No newline at end of file