review basic README files

Author: NHingerl

README.md

@@ -6,26 +6,25 @@
 
 ## Description
 
-This repository provides tangible samples based on the good practices and examples 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) on [help.sap.com](https://help.sap.com/docs/).
 
-The provided samples show the implementation of the guidelines using Infrastructure as Code namely [Terraform](https://www.terraform.io/)/[OpenTofu](https://opentofu.org/). This should support in getting started with a sustainable setup of your SAP BTP accounts following our recommendations.
+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.
 
 ## Content Structure
 
 TODO
 
-## How to obtain support
+## Getting Support
 
-❓ - If you have a *question* you can ask it here in [GitHub Discussions](https://github.com/SAP-samples/btp-admin-guide-samples/discussions/).
+❓ - If you have a *question*, ask it in [GitHub Discussions](https://github.com/SAP-samples/btp-admin-guide-samples/discussions/).
 
-🐞 - If you find a bug, feel free to create a [bug report](https://github.com/SAP-samples/btp-admin-guide-samples/issues/new?assignees=&labels=bug%2Cneeds-triage&projects=&template=bug_report.yml&title=%5BBUG%5D).
-
-💡 - If you have an idea for improvement or a feature request, please open a [feature request](https://github.com/SAP-samples/btp-admin-guide-samples/issues/new?assignees=&labels=enhancement%2Cneeds-triage&projects=&template=feature_request.yml&title=%5BFEATURE%5D).
+🐞 - If you find a bug, please create a [bug report](https://github.com/SAP-samples/btp-admin-guide-samples/issues/new?assignees=&labels=bug%2Cneeds-triage&projects=&template=bug_report.yml&title=%5BBUG%5D).
 
+💡 - If you have an idea for improvement or a feature request, feel free to open a [feature request](https://github.com/SAP-samples/btp-admin-guide-samples/issues/new?assignees=&labels=enhancement%2Cneeds-triage&projects=&template=feature_request.yml&title=%5BFEATURE%5D).
 
 ## Contributing
 
-If you wish to contribute code, offer fixes or improvements, please send a pull request. Due to legal reasons, contributors will be asked to accept a DCO when they create the first pull request to this project. This happens in an automated fashion during the submission process. SAP uses [the standard DCO text of the Linux Foundation](https://developercertificate.org/).
+If you'd like to contribute code, fixes, or improvements, please create a pull request. Due to legal reasons, contributors must accept a DCO. When you create your first pull request to this project, you are automatically asked to accept the DCO. SAP uses [the standard DCO text of the Linux Foundation](https://developercertificate.org/).
 
 ## Code of Conduct
 

sample-setups/README.md

@@ -2,7 +2,7 @@
 
 ## Paradigms
 
-We follow the paradigms of a simple and clear Terraform configuration as laid out in the [Simple, Clear, Maintainable](https://rosesecurity.dev/blog/2024/11/24/terraform-proverbs) blog post of the [Development Log](https://rosesecurity.dev/) especially:
+We follow the paradigms of a simple and clear Terraform configuration as laid out in [Simple, Clear, Maintainable](https://rosesecurity.dev/blog/2024/11/24/terraform-proverbs); especially:
 
 - Clear is better than clever.
 - Modules should be reusable, not rigid.
@@ -13,18 +13,18 @@ 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 Tagging
+## Naming Conventions and Labeling
 
-Ensuring naming conventions is one import aspect when provisioning and managing your SAP BTP account. We will align our samples in accordance to the [Naming Conventions for SAP BTP Accounts](https://help.sap.com/docs/btp/btp-admin-guide/naming-conventions-for-sap-btp-accounts).
+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 dedicated module. Besides the naming we will also include the labels that can be attached to some resources on SAP BTP.
+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).
 
 ## Setup of Directories
 
-The setup of directories as a structuring element for the subaccounts is configured in the folder `basic-setup/directory-setup`. The Details about the setup are described in the [README.md](./basic-setup/directory-setup/README.md) file.
+The folder `basic-setup/directory-setup` contains the setup of directories as a structuring element for the subaccounts. For details, see [README.md](./basic-setup/directory-setup/README.md).
 
 ## Setup of Subaccounts
 
-The setup of subaccounts is configured in the folder `basic-setup/subaccount-setup`. The Details about the setup are described in the [README.md](./basic-setup/subaccount-setup/README.md) file.
+The folder `basic-setup/subaccount-setup` contains the setup of subaccounts. For details, see the [README.md](./basic-setup/subaccount-setup/README.md) file.

sample-setups/basic-setup/directory-setup/README.md

@@ -2,29 +2,43 @@
 
 ## Assumptions
 
-- We assume that we use the directories as structuring element for the subaccounts i.e., in an unmanaged fashion.
+- 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 i.e., the setup of the basic structure from the creation of the operational units namely the subaccounts inside of the directories. The changes on directory level are probably a rare scenario compared to 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 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.
 
 ## Directory Setup
 
-The creation of the directories is steered by a map of objects that define the business data relevant for a directory namely:
+To create the directories, we use a map of objects that define the business data relevant for a directory, such as the following:
 
-- business_unit (`string`): The business unit that owns the directory e.g., HR, IT, Finance
-- costcenter (`string`): Cost center of the business unit
-- directory_contacts (`list(string)`): List of email addresses representing the directory contacts
-- region (`string`): The geographical region of the directory e.g., EMEA
+- business_unit (`string`): The business unit that owns the directory, such as HR, IT, or Sales
+- costcenter (`string`): The cost center of the business unit
+- directory_contacts (`list(string)`): The list of email addresses representing the directory contacts
+- region (`string`): The geographical region of the directory, for example, EMEA
 
-This is input data is reflected by the variables defined in the [variables.tf](./variables.tf) file
+This is input data is reflected by the variables defined in the [variables.tf](./variables.tf) file.
 
-The directories are provisioned via the [main.tf](./main.tf) file which delegates to the module [base-directory-setup](../../modules/base-directory-setup/README.md). This module 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).
+The directories are provisioned with the [main.tf](./main.tf) file, which delegates to the module [base-directory-setup](../../modules/base-directory-setup/README.md). This module 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).
 
-After provisioning the output summarizes the executed setup as given by the [outputs.tf](./outputs.tf) file. Here is an example how the output could look like:
+After provisioning the output, it summarizes the executed setup as given by the [outputs.tf](./outputs.tf) file. See the following example how the output could look like:
 
-![Sample Output for a directory](../../../assets/base-directory-output.png)
+<!-- screenshots are disencouraged because they're harder to keep up to date ![Sample Output for a directory](../../../assets/base-directory-output.png) -->
+
+```json
+Outputs:
+
+directories = {
+  "directory1" = {
+    "business_unit" = "HR"
+    "costcenter" = "123456"
+    "id" = "cf12345f-1234567890"
+    "name" = "Sales-EMEA"
+    "region" = "EMEA"
+  }
+}
+```
 
 ## SAP BTP Administrator's Guide - References
 

sample-setups/basic-setup/subaccount-setup/README.md

@@ -2,64 +2,64 @@
 
 ## Assumptions
 
-- We assume a basic setup of a subaccount is executed by the platform team/ SAP BTP administrator team
-- We assume that the responsibility of the platform team is restricted to a basic setup of a subaccount leaving out app subscriptions and service instance creation.
+- We assume a basic setup of a subaccount is executed by your organization's SAP BTP administrator team, Platform Engineering Team, or Center of Expertise. For details, see [Building Teams](https://help.sap.com/docs/btp/btp-admin-guide/building-teams?locale=en-US&version=Cloud#platform-engineering-team-center-of-excellence).
+- We assume that the responsibility of the Platform Engineering Team is restricted to a basic setup of a subaccount, excluding creation of app subscriptions or service instances.
 
 ## Design Decisions
 
-To keep the Terraform state files clearly separated the setup is done per subaccount i.e. per stage.
+To keep the Terraform state files clearly separated, the setup is done per subaccount, that is, per development stage.
 
 ## Subaccount Setup
 
-The setup of the subaccount comprises:
+The setup of the subaccount comprises the following steps:
 
-- The setup of a subaccount in accordance to the naming conventions and labeling strategy of the company
-- The trust configuration to a custom IdP is configured by default.
-- Default entitlements are added depending on the stage. In addition the requesting team can add additional project specific entitlements ("à la carte entitlements")
-- Optionally a Cloud Foundry Environment is created
+1. The setup of a subaccount following the naming conventions and labeling strategy of your company.
+2. The trust configuration to a custom IdP is configured by default.
+3. Depending on the development stage, default entitlements are added. In addition, the requesting team can add project-specific entitlements ("à la carte entitlements").
+4. Optionally, a Cloud Foundry Environment is created.
 
 ### Naming Conventions and Labels
 
-The naming conventions and labels are centralized in the module [sap-btp-naming-conventions-subaccount](../../modules/sap-btp-naming-conventions-subaccount/README.md). The names and labels are derived based on input variables defined in the [variables.tf](./variables.tf) file.
+The naming conventions and labels are centralized in the module [sap-btp-naming-conventions-subaccount](../../modules/sap-btp-naming-conventions-subaccount/README.md). The input variables (see [variables.tf](./variables.tf)) define the names and labels.
 
-### Validations for Geographies and BTP Regions
+### Validations for Geographies and SAP BTP Regions
 
-According to the SAP BTP Administrators Guide one part of the naming is the geographical region. To ensure that this region fits to the subaccount region, a validation is implemented in the [variables.tf](./variables.tf) file. The validation checks if the region of the subaccount is part of the geographical region. The geographical regions are defined in a local variables defined in the [main.tf](main.tf) file.
+You can include the geographical region in your naming conventions. To ensure that this region fits to the subaccount region, the [variables.tf](./variables.tf) file validates if the region of the subaccount is part of the geographical region. The geographical regions are defined as local variables in the [main.tf](main.tf) file.
 
 ### Setup of Entitlements
 
-The setup of entitlements is split into two parts:
+The setup of entitlements is split into two files:
 
-- The default entitlements that are defined per stage and sourced from the module [](../../modules/sap-btp-subaccount-default-entitlements/README.md)
-- Optional additional entitlements that might be needed due to project specific requirements. These entitlements are defined in the [variables.tf](./variables.tf) file
+- The default entitlements that are defined per development stage and sourced from the module (see [SAP BTP - Default Subaccount Entitlements](../../modules/sap-btp-subaccount-default-entitlements/README.md)).
+- Optional additional entitlements, depending on project-specific requirements. These entitlements are defined in the [variables.tf](./variables.tf) file
 
 The configuration merges the two files and adds the entitlements to the subaccount.
 
-To ease the provisioning of entitlements we use the Terraform community module [SAP BTP Entitlements Management with Terraform Module: sap-btp-entitlements](https://registry.terraform.io/modules/aydin-ozcan/sap-btp-entitlements/btp/latest).
+For easier provisioning of entitlements, we use the Terraform community module [SAP BTP Entitlements Management with Terraform Module: sap-btp-entitlements](https://registry.terraform.io/modules/aydin-ozcan/sap-btp-entitlements/btp/latest).
 
-### Setup of Cloud Foundry Environment
+### Setup of SAP BTP, Cloud Foundry Runtime
 
-The setup of a Cloud Foundry environment is optional. The caller can decide if a Cloud Foundry environment is required or not e.g. when setting up a shared subaccount. The boolean variable is `provision_cf_environment` in the [variables.tf](./variables.tf) file.
+The setup of a Cloud Foundry runtime is optional. The caller can decide if a Cloud Foundry runtime is required or not, for example, when setting up a shared subaccount. The Boolean variable is `provision_cf_environment` in the [variables.tf](./variables.tf) file.
 
-The configuration of the setup is done in the corresponding module [`sap-btp-environment/cloudfoundry`](../../modules/sap-btp-environment/cloudfoundry/README.md).
+The setup is configured in the corresponding module [`sap-btp-environment/cloudfoundry`](../../modules/sap-btp-environment/cloudfoundry/README.md).
 
-### Setup of Kyma Environment
+### Setup of SAP BTP, Kyma Runtime
 
-The setup of a Kyma environment is optional. The caller can decide if a Kyma environment is required or not e.g. when setting up a shared subaccount. The boolean variable is `provision_kyma_environment` in the [variables.tf](./variables.tf) file.
+The setup of a Kyma runtime is optional. The caller can decide if a Kyma runtime is required or not, for example, when setting up a shared subaccount. The Boolean variable is `provision_kyma_environment` in the [variables.tf](./variables.tf) file.
 
-If the Kyma environment is requested, the variable `kyma_administrators` in the [variables.tf](./variables.tf) file must be filled with the users that should be assigned as administrators. This condition is validated
+If the Kyma runtime is requested, the users that should be assigned as administrators must be entered in the variable `kyma_administrators` in the [variables.tf](./variables.tf) file. This condition is validated.
 
-The configuration of the setup is done in the corresponding module [`sap-btp-environment/kyma`](../../modules/sap-btp-environment/kyma/README.md).
+The setup is configured in the corresponding module [`sap-btp-environment/kyma`](../../modules/sap-btp-environment/kyma/README.md).
 
 ### Output
 
-The output defined in the [outputs.tf](./outputs.tf) file returns the main information relevant for the development team namely:
+The output defined in the [outputs.tf](./outputs.tf) file returns the main information relevant for the development team, such as:
 
-- a link to the subaccount
-- The ID of the Cloud Foundry org if a Cloud Foundry environment is created
-- The API endpoint of the Cloud Foundry environment if a Cloud Foundry environment is created
-- The URL to the Kyma dashboard if a Kyma environment is created
-- The URL to the Kubeconfig file for the Kyma runtime if a Kyma environment is created
+- A link to the subaccount
+- If a Cloud Foundry runtime is created, the ID of the Cloud Foundry org
+- If a Cloud Foundry runtime is created, the API endpoint of the Cloud Foundry environment
+- If a Kyma runtime is created, the URL to the Kyma dashboard
+- If a Kyma runtime is created, the URL to the Kubeconfig file for the Kyma runtime
 
 ## SAP BTP Administrator's Guide - References