Improve readability of Kubernetes page

[sanmai-NL]

Break down command line so as to keep arguments on separate lines, and indent subcommands and their arguments.

What is the goal of this PR?

We improved readability of the deployment docs.

What are the changes implemented in this PR?

We broke down and indented command lines consistently.

[typedb-bot]

PR Review Checklist

Do not edit the content of this comment. The PR reviewer should simply update this comment by ticking each review item below, as they get completed.

---

Trivial Change

• This change is trivial and does not require a code or architecture review.

Code

• Packages, classes, and methods have a single domain of responsibility.
• Packages, classes, and methods are grouped into cohesive and consistent domain model.
• The code is canonical and the minimum required to achieve the goal.
• Modules, libraries, and APIs are easy to use, robust (foolproof and not errorprone), and tested.
• Logic and naming has clear narrative that communicates the accurate intent and responsibility of each module (e.g. method, class, etc.).
• The code is algorithmically efficient and scalable for the whole application.

Architecture

• Any required refactoring is completed, and the architecture does not introduce technical debt incidentally.
• Any required build and release automations are updated and/or implemented.
• Any new components follows a consistent style with respect to the pre-existing codebase.
• The architecture intuitively reflects the application domain, and is easy to understand.
• The architecture has a well-defined hierarchy of encapsulated components.
• The architecture is extensible and scalable.

[sanmai-NL]

Please dedent this line one level.

[alexjpwalker]

Thanks for the PR! But I don't think this is necessarily an improvement to readability for users. We would rarely break down a command-line command by putting each component on its own line. For example,

kubectl \
  create \
    secret \

strikes me as less readable than kubectl create secret.

This is also in line with our other command-line scripts across the entirety of Docs, and our source code in general across the vaticle org; we use newlines conservatively so that the code / command is more "compact".

[sanmai-NL]

It's still more readable, just less pretty.

Why do you think the compactness of source code or command lines in and of itself is a quality in documentation? It is not, again, the expert may find it less attractive, but the novice should learn to parse the command and source code first.

[alexjpwalker]

People who are used to reading/writing commands in a tree-like structure will find them more readable, those used to putting them on one line will find that more readable. From this we can infer readability is subjective.

This is how Kubernetes' documentation writes their examples: https://kubernetes.io/docs/reference/kubectl/cheatsheet/

# Partially update a node
kubectl patch node k8s-node-1 -p '{"spec":{"unschedulable":true}}'

# Update a container's image; spec.containers[*].name is required because it's a merge key
kubectl patch pod valid-pod -p '{"spec":{"containers":[{"name":"kubernetes-serve-hostname","image":"new image"}]}}'

# Update a container's image using a json patch with positional arrays
kubectl patch pod valid-pod --type='json' -p='[{"op": "replace", "path": "/spec/containers/0/image", "value":"new image"}]'

# Disable a deployment livenessProbe using a json patch with positional arrays
kubectl patch deployment valid-deployment  --type json   -p='[{"op": "remove", "path": "/spec/template/spec/containers/0/livenessProbe"}]'

# Add a new element to a positional array
kubectl patch sa default --type='json' -p='[{"op": "add", "path": "/secrets/1", "value": {"name": "whatever" } }]'

# Update a deployment's replica count by patching its scale subresource
kubectl patch deployment nginx-deployment --subresource='scale' --type='merge' -p '{"spec":{"replicas":2}}'