Align documentation guidelines

doc/contribute/documenting.md

@@ -14,7 +14,7 @@ Documenting OpenCAPIF is limited to active contributors. So, if you:
 
 [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 it works?
+### How does it work?
 
 There are 2 ways to upgrade documentation published on the [OCF Documentation] website:
 
@@ -25,14 +25,15 @@ There are 2 ways to upgrade documentation published on the [OCF Documentation] w
 
 This documentation repository has 2 protected branches:
 
-  * **main**: this branch will store the information stable;
-  * **develop**: any change uploaded on this branch will upgrade **develop** version of the documentation published on the [OCF Documentation] website.
+  * **main**: stable timeline on which tags are made;
+  * **develop**: edge timeline, also published on the [OCF 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:
@@ -54,9 +55,11 @@ As you can see here, we have at the time of writing this page, 5 main sections:
   * Contribute: details about how to contribute code and docs;
   * FAQ.
 
+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 OpenCAPIF, also including the version.
+The page shown first is at **doc/index.md**. That page should be updated with the latest changes of OpenCAPIF and should reference the version (useful shortcut is ``{{{ documentation_version }}}``).
 
 ## Getting Started
 
@@ -75,14 +78,26 @@ cd ./documentation
 git checkout develop
 ```
 
-3) Setup a local ``mkdocs`` server, using a virtual environment:
+3) Setup a virtual environment:
+
+* On Linux/macOS:
+
+  ```bash
+  python3 -m venv venv # Linux/macOS
+  source venv/bin/activate #Linux/macOS
+  ```
+
+* On Windows:
+
+  ```bash
+  python -m venv venv # Windows
+  venv\Scripts\activate # Windows
+  ```
+
+4) Setup a local ``mkdocs`` server by installing requirements:
 
 ```bash
-python3 -m venv venv
-source venv/bin/activate
-python -m pip install mkdocs
-python -m pip install mkdocs-material
-python -m pip install mike
+python -m pip install -r requirements.txt
 ```
 
 4) Wait for all downloads to finish and start the local ``mkdocs`` server:
@@ -104,18 +119,17 @@ To update the documentation properly during development, follow those additional
 3. Update the documentation and any relevant parts (ie: the ``index.md`` with new functionalities for the latest version or if a new test plan has been defined, remember to *update the test plan documentation*);
 4. Check if errors are not being produced by ``mkdocs`` [locally](#getting-started);
 5. Commit and push changes to the new branch;
-6. Create a merge/pull request;
+6. Create a merge/pull request towards **develop**;
 7. Send the request for review and approval to at least one **TSC Member**.
 
-> The documentation website supports branches, so your accepted changes will be reflected to the **develop** branch which becomes the **release** branch after each corresponding cycle.
+> The documentation website supports branches, so your accepted changes will be reflected to the **develop** branch which then becomes the **release** branch after each corresponding cycle.
 
 ### Release a New Version of the Documentation
 
 When **OpenCAPIF** code repository is ready for a new release, we need to follow these steps (made by a **TSC Member**):
 
-1. Create a new branch with the released version, and merge it to **develop**;
-2. Create a Merge request from **develop** to **main**;
-3. When develop is merged to **main**, then we need to **create a tag with the released version**.
+1. Create a PR from **develop** towards **main**;
+2. When **develop** is merged to **main**... then **create a tag with the released version** scheme... and you're done!
 
 [OCF Web]: https://ocf.etsi.org/ "OCF Web"
 [OCF Documentation]: https://ocf.etsi.org/documentation/ "OCF Documentation"

requirements.txt

+mkdocs
+mkdocs-material
+mkdocs-glightbox
+mkdocs-markdownextradata-plugin
+mike
\ No newline at end of file