docs: refinement after review comments

Author: lechnerc77

README.md

@@ -6,7 +6,7 @@
 
 ## Description
 
-This repository provides samples based on the recommendations given in the [SAP BTP Administrator's Guide](https://help.sap.com/docs/btp/btp-admin-guide/btp-admin-guide) on [help.sap.com](https://help.sap.com/docs/).
+This repository provides samples based on the recommendations given in the [SAP BTP Administrator's Guide](https://help.sap.com/docs/btp/btp-admin-guide/btp-admin-guide) specifically the section ["Setting Up Your Account Model"](https://help.sap.com/docs/btp/btp-admin-guide/setting-up-your-account-model).
 
 These samples show the implementation of the recommendations using Infrastructure as Code, namely [Terraform](https://www.terraform.io/) or [OpenTofu](https://opentofu.org/). They help you getting started with a sustainable setup of your SAP BTP accounts following our best practices.
 

assets/SAP_BTP_Solution_Diagram.pptx

@@ -13,13 +13,13 @@ We follow the paradigms of a simple and clear Terraform configuration as laid ou
 - Name with underscores, not dashes.
 - Using locals makes code descriptive and maintainable.
 
-## Naming Conventions and Labeling
+Another important paradigm is avoiding a monolithic Terraform state (*"Terralith"*). Hence, there is no single Terraform configuration for a complete SAP BTP account. Instead, we split the setup in configurations that are provisioned and managed seperately.
 
-Consistent naming conventions are one import aspect when provisioning and managing your SAP BTP account. Our samples follow the [Naming Conventions for SAP BTP Accounts](https://help.sap.com/docs/btp/btp-admin-guide/naming-conventions-for-sap-btp-accounts).
+## Overview
 
-To ensure consistent naming of your resources, we encapsulate the guidelines in a dedicated module. Besides the naming, we also include the labels that can be attached to some resources on SAP BTP.
+The basic setup showcases the setup of directories and subaccounts as given in this overview:
 
-We have created one module for the level of the [directory](./modules/sap-btp-naming-conventions-directory/README.md) and one for the level of the [subaccount](./modules/sap-btp-naming-conventions-subaccount/README.md).
+![Overview Basic Setup](../assets/basic-setup-overview.png)
 
 ## Setup of Directories
 
@@ -28,3 +28,26 @@ The folder `basic-setup/directory-setup` contains the setup of directories as a
 ## Setup of Subaccounts
 
 The folder `basic-setup/subaccount-setup` contains the setup of subaccounts. For details, see the [README.md](./basic-setup/subaccount-setup/README.md) file.
+
+## Modules
+
+We have created a set of modules to encapsulate the reusable parts of the setup. The modules are located in the folder `modules`. Each module has its own README file that describes the module and its usage.
+
+### Naming Conventions and Labeling
+
+Consistent naming conventions are one import aspect when provisioning and managing your SAP BTP account. Our samples follow the [Naming Conventions for SAP BTP Accounts](https://help.sap.com/docs/btp/btp-admin-guide/naming-conventions-for-sap-btp-accounts).
+
+To ensure consistent naming of your resources, we encapsulate the guidelines in a dedicated module. Besides the naming, we also include the labels that can be attached to some resources on SAP BTP.
+
+We have created one module for the level of the [directory](./modules/sap-btp-naming-conventions-directory/README.md) and one for the level of the [subaccount](./modules/sap-btp-naming-conventions-subaccount/README.md).
+
+### Directory Setup
+
+The module [base-directory-setup](./modules/base-directory-setup/README.md) is used to create the directories. It combines the corresponding module containing the naming and labeling conventions for a directory, and calls the Terraform resource [btp_directory](https://registry.terraform.io/providers/SAP/btp/latest/docs/resources/directory).
+
+### Subaccount Setup
+
+The reusable parts of the subaccount setup are:
+
+- The module [SAP BTP - Default Subaccount Entitlements](./modules/sap-btp-subaccount-default-entitlements/README.md) encapsulates the default entitlements for SAP BTP subaccounts. It distinguishes between the different development stages of the environment (Dev, Test, Prod, Shared) and provides the default data of entitlements for each stage. The entitlement is executed in the configuration of the [basic setup of the subaccount](./basic-setup/directory-setup/README.md)
+- The creation of the different SAP BTP environemnts are encapsulated in modules for [Cloud Foundry](./modules/sap-btp-environment/cloudfoundry/README.md) and [Kyma](./modules/sap-btp-environment/kyma/README.md).

assets/basic-setup-overview.png

@@ -1,13 +1,10 @@
 # Sample Setup for a Basic Directory Structure
 
-## Assumptions
-
-- We assume that we use the directories as structuring element for the subaccounts; that is, in an unmanaged fashion.
-- We assume that we do the directory setup in one run for all involved departments.
-
 ## Design Decisions
 
-We decouple the directory creation (the setup of the basic structure) from the creation of the operational units (the subaccounts within the directories). Typically, changes on directory level happen less frequently than changes in the subaccounts additionally depending on their stage. We want to avoid side effects as well as lengthy state refreshes and keep the state of the directories separate.
+- We use the directories as structuring element for the subaccounts; that is, in an unmanaged fashion.
+- We decouple the directory creation (the setup of the basic structure) from the creation of the operational units (the subaccounts within the directories). Typically, changes on directory level happen less frequently than changes in the subaccounts additionally depending on their stage. We want to avoid side effects as well as lengthy state refreshes and keep the state of the directories separate.
+- We do the directory provisioning and management as one unit for all involved departments.
 
 ## Directory Setup
 
@@ -32,7 +29,7 @@ directories = {
     "business_unit" = "HR"
     "costcenter" = "123456"
     "id" = "cf12345f-1234567890"
-    "name" = "Sales-EMEA"
+    "name" = "HR-EMEA"
     "region" = "EMEA"
   }
 }