otc_metadata/data/README.md

@@ -1,8 +1,26 @@
-# Metadata Overview
+# 📁 data/
 
-The metadata of each service is listed in the following folders. The folder contain the "database" information of the services grouped by its purpose as listed below.
+This directory is the core of the metadata structure for Open Telekom Cloud Service Documentation. It contains structured definitions for services, their document types, categories, and repository configurations.
 
-* **services**: contains each service
-* **service_categories**: each service belongs to one service categorie
-* **documents**: every service has none to multiple documents e.g. UMN or API-Ref. If the service has at least one document the "service based view" (SVB) is used. Otherwise the root document starts at the landing page of the service.
-* **repositories**: contains the location of the source code for each helpcenter instance
+## 📂 Folder Overview
+
+| Folder Name         | Description                                                                 |
+|---------------------|-----------------------------------------------------------------------------|
+| `services/`          | Contains metadata for each individual service, including its cloud regions and access teams. |
+| `documents/`         | Holds metadata about documentation types (e.g., user guides, API refs) for each service and cloud region. |
+| `service_categories/`| Lists available service categories used to group services (e.g., "Application", "Database"). |
+| `repositories/`      | Defines where the documentation source code is located (GitHub or Gitea) for each service per cloud environment. |
+
+## 📦 Usage
+
+These metadata files are used to:
+- Build documentation portals.
+- Generate links and visibility rules dynamically.
+- Control contributor access.
+- Connect documentation to source control repositories.
+
+Each subfolder contains its own `README.md` with detailed field references and options.
+
+## 📎 Example Structure
+
+![Folder Structure](./folder_structure.png)