[PRA-154] docs: Polish the terminology capitalisation (#188)

izmalk · web-flow · commit b603f82aca88 · 2026-02-12T00:41:19.000Z
* Updated terminology capitalisation
* Sorted the custom_wordlist
diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt
@@ -3,39 +3,74 @@ addon
 addons
 backend
 backends
+Canonical's
 Charmcraft
 cjk
+conformant
 cryptographically
+csv
+CVEs
 databag
 databags
+datalake
+datalakes
+DBeaver
+dbeaver
 dvipng
 fonts
 freefont
+Furo
 github
+GitHub
 GPG
 GPU
 GPUs
 gyre
-https
 html
-io
+https
 Intersphinx
+io
+ip
+Kaggle
+kaggle
+kubeconfig
+lakehouse
+landscape
 lang
+lastmod
 LaTeX
 latexmk
+loadbalancer
+loadbalancers
+metastore
 Multipass
+MyST
+Open Graph
 otf
+PDF
+performant
+plaintext
 plantuml
 PNG
 postgres
 postgresql
+PR
+PVCs
 Pygments
 pymarkdown
 QEMU
-Rockcraft
+Read the Docs
 readthedocs
+reStructuredText
+Rockcraft
 rst
+serverless
+Servlet
 sitemapindex
+Sphinx
+Spread
+spread_test_example
+Storages
 subproject
 subprojects
 SVG
@@ -45,6 +80,7 @@ TOC
 toctree
 txt
 uncommenting
+URL
 utils
 VMs
 WCAG
@@ -54,49 +90,5 @@ wordlist
 xetex
 xindy
 xml
-ip
-spread_test_example
-Furo
-PDF
-Open Graph
-MyST
-YouTube
-reStructuredText
-GitHub
-Sphinx
-URL
-PR
-Read the Docs
-Spread
-landscape
-lastmod
 yaml
-conformant
-PVCs
-Servlet
-Storages
-datalake
-datalakes
-kubeconfig
-CVEs
-Canonical's
-metastore
-DBeaver
-lakehouse
-serverless
-Kaggle
-GPUs
-Kubeconfig
-ConfigMaps
-plaintext
-databag
-serverless
-performant
-configmap
-configmaps
-loadbalancer
-loadbalancers
-kaggle
-csv
-dbeaver
-
+YouTube
diff --git a/docs/explanation/configuration.md b/docs/explanation/configuration.md
@@ -26,7 +26,7 @@ the latter sources on top of previous ones in case of multi-level definitions.
 
 ## Group configuration
 
-Group configurations are centrally stored as secrets in K8s,
+Group configurations are centrally stored as Secret objects,
 and managed by `spark-integration-hub-k8s` charm that takes care of managing
 their lifecycle from creation, modification and deletion.
 See the
@@ -36,7 +36,7 @@ setting up group configurations. These are valid across users, machines and sess
 
 ## User configuration
 
-User configurations are centrally stored as secrets in K8s, but they are
+User configurations are centrally stored as Secret objects, but they are
 managed by the user using the `spark-client` snap and/or `spark8t` Python library.
 For more information, please refer to
 [here](/how-to/manage-service-accounts/using-spark-client-snap) for the `spark-client`
diff --git a/docs/explanation/cryptography.md b/docs/explanation/cryptography.md
@@ -76,7 +76,7 @@ The communication between K8s and Spark8t is always encrypted by default with au
 Since Apache Spark Client snap is a wrapper around this library, the communication between the snap and the K8s cluster
 is also authenticated and encrypted.
 
-The Spark8t Python library stores Apache Spark properties as Kubernetes Secrets because these properties may contain
+The Spark8t Python library stores Apache Spark properties as Secret objects because these properties may contain
 credentials like database password, AWS S3 access key, secret keys, etc.
 These are encrypted both at rest and in transit by default by the underlying K8s engine.
 
@@ -135,7 +135,7 @@ Azure object storages. Credentials are stored in peer-relation data for S3 Integ
 the Azure Object storage, and they are communicated to other charms (Spark History Server, Integration Hub
 and Apache Kyuubi) via relation databag.
 
-Integration Hub stores the credentials into Kubernetes Secrets to be made available for Spark jobs.
+Integration Hub stores the credentials into Secret objects to be made available for Spark jobs.
 Driver and executors store configuration files (where credential information is stored) unencrypted in `/etc/spark8t/conf`.
 Apache Kyuubi stores credentials in unencrypted configuration files in `/opt/spark/conf`, to be used to configure
 Apache Spark Engine, and `/opt/kyuubi/conf`, to be used to configure the Kyuubi Server.
diff --git a/docs/explanation/monitoring.md b/docs/explanation/monitoring.md
@@ -49,9 +49,9 @@ Every pod needs to be run using a service account that needs to be set up with t
 correct permissions. Charmed Apache Spark tooling, i.e. the `spark-client` snap
 and the `spark8t` Python libraries, make sure that service account are 
 created correctly and configured appropriately. The driver pod must be running
-with a service account that is able to create pods, services and configmaps in 
+with a service account that is able to create Pods, Services and ConfigMaps in 
 order to correctly spawn executors. Moreover, Charmed Apache Spark service accounts
-also store Apache Spark configuration centrally in Kubernetes as secrets, that must 
+also store Apache Spark configuration centrally in Kubernetes as Secret objects, that must 
 be readable/writable depending on their scope. Please refer to the explanations 
 about the [Charmed Apache Spark hierarchical configuration](explanation-configuration) for more information.
 
diff --git a/docs/how-to/deploy/environment.md b/docs/how-to/deploy/environment.md
@@ -308,7 +308,7 @@ terraform output
 # resource_group_name = "TestSparkAKSRG"
 ```
 
-#### Generating the Kubeconfig file
+#### Generating the kubeconfig file
 
 To generate the `kubeconfig` file for connecting the client to the newly created cluster:
 
diff --git a/docs/how-to/manage-service-accounts/using-spark-client-snap.md b/docs/how-to/manage-service-accounts/using-spark-client-snap.md
@@ -17,7 +17,7 @@ using Juju relations. For more information about how to use the configuration hu
 ```
 
 ```{caution}
-The following commands assume that you have administrative permission on the namespaces (or on the Kubernetes cluster) so that the corresponding resources (such as service accounts, secrets, roles, and role bindings) can be created and deleted. 
+The following commands assume that you have administrative permission on the namespaces (or on the Kubernetes cluster) so that the corresponding resources (such as ServiceAccounts, Secrets, Roles, and RoleBindings) can be created and deleted. 
 ```
 
 ## Create service account
@@ -98,7 +98,7 @@ spark-client.service-account-registry get-primary
 
 ## Cleanup a service account
 
-To delete the service account together with the other resources created, e.g. secrets, role, role-bindings, etc.:
+To delete the service account together with the other resources created, e.g. Secrets, Roles, RoleBindings, etc.:
 
 ```bash
 spark-client.service-account-registry delete --username demouser --namespace demonamespace 
diff --git a/docs/tutorial/1-environment-setup.md b/docs/tutorial/1-environment-setup.md
@@ -166,7 +166,7 @@ The MicroK8s setup is complete.
 
 ## The `spark-client` snap
 
-For Apache Spark jobs to be running run on top of Kubernetes, a set of resources (service account, associated roles, role bindings etc.) need to be created and configured.
+For Apache Spark jobs to be running run on top of Kubernetes, a set of resources (ServiceAccount, associated Roles, RoleBindings etc.) need to be created and configured.
 To simplify this task, the Charmed Apache Spark solution offers the `spark-client` snap. Install the snap: 
 
 ```bash
@@ -179,14 +179,14 @@ Let's create a Kubernetes namespace for us to use as a playground in this tutori
 kubectl create namespace spark
 ```
 
-We will now create a Kubernetes service account that will be used to run the Spark jobs. The creation of the service account can be done using the `spark-client` snap, which will create necessary roles, role bindings and other necessary configurations along with the creation of the service account:
+We will now create a ServiceAccount that will be used to run the Spark jobs. The creation of the ServiceAccount can be done using the `spark-client` snap, which will create necessary Roles, RoleBindings and other necessary configurations along with the creation of the ServiceAccount:
 
 ```bash
 spark-client.service-account-registry create \
   --username spark --namespace spark
 ```
 
-This command does a number of things in the background. First, it creates a service account in the `spark` namespace with the name `spark`. Then it creates a role with name `spark-role` with all the required RBAC permissions and binds that role to the service account by creating a role binding. 
+This command does a number of things in the background. First, it creates a ServiceAccount in the `spark` namespace with the name `spark`. Then it creates a Role with name `spark-role` with all the required RBAC permissions and binds that Role to the ServiceAccount by creating a RoleBinding. 
 
 These resources can be viewed with `kubectl get` commands as follows:
 
@@ -363,7 +363,7 @@ With the access key, secret key, and the endpoint properly configured, you shoul
 
 For Apache Spark to be able to access and use our local S3 bucket, we need to provide a few configuration options including the bucket endpoint, access key and secret key.
 
-In the Charmed Apache Spark solution, these configurations are stored in a Kubernetes secret and bound to a Kubernetes service account. When Spark jobs are executed using that service account, all associated configurations are automatically retrieved and supplied to Apache Spark.
+In the Charmed Apache Spark solution, these configurations are stored in a Secret object and bound to a ServiceAccount. When Spark jobs are executed using that service account, all associated configurations are automatically retrieved and supplied to Apache Spark.
 
 The S3 configurations can be added to the existing `spark` service account with the following command:
 
diff --git a/docs/tutorial/4-history-server.md b/docs/tutorial/4-history-server.md
@@ -136,16 +136,16 @@ The Spark History Server comes with a Web UI for users to view and monitor the S
 
 ### Setup
 
-The web UI can be accessed at port 18080 of the IP address of the `spark-history-server-k8s/0` unit. However, it's good practice to access it via a Kubernetes Ingress rather than directly accessing the unit's IP address. Using an Ingress will allow us to have a common entrypoint to the applications running in the Juju model. 
+The web UI can be accessed at port 18080 of the IP address of the `spark-history-server-k8s/0` unit. However, it's good practice to access it via an ingress rather than directly accessing the unit's IP address. Using an ingress will allow us to have a common entrypoint to the applications running in the Juju model. 
 
-Let's add an Ingress by deploying and integrating the [`traefik-k8s`](https://charmhub.io/traefik-k8s) charm with `spark-history-server-k8s`:
+Let's add an ingress by deploying and integrating the [`traefik-k8s`](https://charmhub.io/traefik-k8s) charm with `spark-history-server-k8s`:
 
 ```bash
 juju deploy traefik-k8s --channel latest/stable --trust
 juju integrate traefik-k8s spark-history-server-k8s
 ```
 
-Now that Traefik has been deployed and configured, we can fetch the Ingress URL of the Spark History Server by running the `show-proxied-endpoints` action on the Traefik charm:
+Now that Traefik has been deployed and configured, we can fetch the ingress URL of the Spark History Server by running the `show-proxied-endpoints` action on the Traefik charm:
 
 ```bash
 juju run traefik-k8s/0 show-proxied-endpoints
diff --git a/python/CONTRIBUTING.md b/python/CONTRIBUTING.md
@@ -89,7 +89,20 @@ For documentation in this repository the following conventions are applied (see
 The full form must be used at least once per page.
 The full form must be used at the first entry to the page’s headings, body of text, callouts, and graphics.
 For subsequent usage, the full form can be substituted by alternatives.
+### Kubernetes Terminology
 
+When documenting Kubernetes concepts, follow the [Kubernetes Documentation Style Guide](https://kubernetes.io/docs/contribute/style/style-guide/#use-upper-camel-case-for-api-objects) for API object capitalization:
+
+- **Use UpperCamelCase** (PascalCase) when referring specifically to Kubernetes API objects: Pod, Service, Namespace, ConfigMap, Secret, Ingress, Deployment, Node, etc.
+- **Use lowercase** when generally discussing the concept or referring to instances in prose.
+
+For example, "The Pod object contains a `hostPath` field" (API reference) vs "the pod is running on node-1" (general discussion).
+
+Special cases:
+
+- **kubeconfig**: Use lowercase when referring to the configuration file (e.g., "update the kubeconfig file").
+- **KUBECONFIG**: Use uppercase when referring to the environment variable.
+- **Product names**: Capitalize properly (e.g., "Azure Kubernetes Service", "Amazon Elastic Kubernetes Service").
 ## Canonical Contributor Agreement
 
 Canonical welcomes contributions to Charmed Apache Spark. Please check out our [contributor agreement](https://ubuntu.com/legal/contributors) if you're interested in contributing to the solution.
