Add understading the basics app dev (#1005)

* Address feedback on Vale PR

* Address more feedback on Vale PR

* Understand the basics for application developers

* Add Elastisys Training

* Make pre-commit happy

CONTRIBUTING.md

@@ -3,7 +3,9 @@
 - Done today is better than perfect tomorrow.
 - Write for the project, not the company.
 - A picture is worth 1000 words. Use Graphviz, Terminal screenshots, or GIFs. Focus on the content, leave aesthetics for another day. Prefer PNG with a width of 1200px.
-- Perspective: Put yourself in the shoes of the user or administrator. What documentation would you like to read as a newcomer?
+- Perspective: Put yourself in the shoes of the application developer or administrator. What documentation would you like to read as a newcomer?
+    - We expect application developers to [understand the basics](docs/user-guide/understand-the-basics.md).
+    - We expect platform administrators to [understand the basics](docs/operator-manual/understand-the-basics.md).
 - Use "we" for the writer(s). Use "you" for the reader.
 - Write in [plain English](http://www.plainenglish.co.uk/how-to-write-in-plain-english.html).
 - Ordering of ideas: Aim for the happy flow: How would a first-time user/administrator interact with the system? In what order would they do things?

docs/adr/0006-use-standard-kubeconfig-mechanisms.md

@@ -6,7 +6,7 @@
 
 ## Context and Problem Statement
 
-To increase adoption of Welkin, we were asked to observe the [Principle of Least Astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment). Currently, Welkin's handing of kubeconfig is astonishing. Most tools in the ecosystem use the standard `KUBECONFIG` environment variable and KUBECONFIG context implemented in the client-go library. These tools leave it up to the user to set `KUBECONFIG` or use the default `~/.kube/config`. Similarly, there is a default KUBECONFIG context which can be overwritten via command-line. Tools that get cluster credentials generate a context related to the name of the cluster.
+To increase adoption of Welkin, we were asked to observe the [Principle of Least Astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment). Currently, Welkin's handing of kubeconfig is astonishing. Most tools in the ecosystem use the standard `KUBECONFIG` environment variable and kubeconfig context implemented in the client-go library. These tools leave it up to the user to set `KUBECONFIG` or use the default `~/.kube/config`. Similarly, there is a default kubeconfig context which can be overwritten via command-line. Tools that get cluster credentials generate a context related to the name of the cluster.
 
 Tools that behave as such include:
 

docs/adr/0025-local-storage.md

@@ -23,7 +23,7 @@ How should we expose local storage to Managed Services?
 - Use local storage with [local-volume-provisioner](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner).
 - Use local storage with [local-path-provisioner](https://github.com/rancher/local-path-provisioner)
 - Use [`hostPath`](https://kubernetes.io/docs/concepts/storage/volumes/#hostpath)
-- Use [local](https://kubernetes.io/docs/concepts/storage/volumes/#local)
+- Use [`local`](https://kubernetes.io/docs/concepts/storage/volumes/#local)
 
 ## Decision Outcome
 
@@ -48,4 +48,4 @@ When using the local-volume-provisioner please create dedicated partitions and m
 - [local-volume-provisioner](https://github.com/kubernetes-sigs/sig-storage-local-static-provisioner/tree/v2.5.0)
 - [local-path-provisioner](https://github.com/rancher/local-path-provisioner)
 - [`hostPath`](https://kubernetes.io/docs/concepts/storage/volumes/#hostpath)
-- [local](https://kubernetes.io/docs/concepts/storage/volumes/#local)
+- [`local`](https://kubernetes.io/docs/concepts/storage/volumes/#local)

docs/user-guide/understand-the-basics.md

@@ -0,0 +1,14 @@
+# Understand the Basics
+
+!!!Elastisys "For Elastisys Managed Services Customers"
+    Elastisys is an Authorized Linux Foundation Training Partner and CNCF Certified Kubernetes Training Partner (KTP).
+    Consider leveraging [Elastisys Training](https://elastisys.com/training/) to quickly get your application team up-to-speed.
+
+Before effectively using Welkin, you need to understand some basics.
+This section provides some useful links to build up this understanding.
+
+- [A Beginner-Friendly Introduction to Containers, VMs and Docker](https://medium.freecodecamp.org/a-beginner-friendly-introduction-to-containers-vms-and-docker-79a9e3e119b)
+- Kubernetes Application Development
+    - We recommend [Linux Foundation Certified Kubernetes Application Developer (CKAD)](https://training.linuxfoundation.org/certification/certified-kubernetes-application-developer-ckad/)
+- [Helm](https://helm.sh)
+    - We recommend [Managing Kubernetes Applications with Helm (LFS244)](https://training.linuxfoundation.org/training/managing-kubernetes-applications-with-helm-lfs244/)

mkdocs.yml

@@ -140,6 +140,7 @@ nav:
   - "Mission and Vision": "mission-and-vision.md"
   - "For Application Developers":
       - "Overview": "user-guide/index.md"
+      - "Understand the Basics": "user-guide/understand-the-basics.md"
       - "Getting Started":
           - "Step 1: Prepare": "user-guide/prepare.md"
           - "Step 2: Deploy": "user-guide/deploy.md"