chore(best-practices): bring items up to date

knowledge base/best practices.md

@@ -1,6 +1,6 @@
 # OAM best practices
 
-What really worked for me.
+What really worked for me personally, or in my experience.
 
 1. [Generic concepts](#generic-concepts)
 1. [Teamwork](#teamwork)
@@ -43,7 +43,7 @@ What really worked for me.
 - Stop [abstracting away][we have used too many levels of abstractions and now the future looks bleak] stuff that does
   not need to be (`docker-cli`/`kubectl` wrappers mapping features 1-to-1, anyone?).
 - Beware of complex things that _should be simple_.<br/>
-  E.g., google what the _[SAFe] delusion_ is.
+  E.g., check what the _[SAFe] delusion_ is.
 - Focus on what matters, but also set time aside to work on the rest.<br/>
   Check [Understanding the pareto principle (the 80/20 rule)].
 - Learn from your (and others') mistakes.<br/>
@@ -53,11 +53,11 @@ What really worked for me.
   [abstractions][we have used too many levels of abstractions and now the future looks bleak].
 - Keep different parts **de**coupled where possible, the same way
   [_interfaces_ are used in programming][what does it mean to program to interfaces?].<br/>
-  This allows for quick and (as much as possible) painless switch between technologies.
+  Allows for quick and (as much as possible) painless switch between technologies.
 - The _one-size-fits-all_ approach is a big fat lie.<br/>
-  You'll end up with stiff, hard to change results that satisfy nobody. This proved particularly true with regards to
-  templates and pipelines.<br/>
-  Stop designing systems that _should work for everybody at all times_.
+  One'll end up with stiff, hard to change results that satisfy nobody. This proved particularly true with regards to
+  _templates_ and _pipelines_.<br/>
+  Stop designing systems that _should work for everybody at all times_. Prefer safe defaults instead.
 - Choose tools based on **how helpful** they are **to you** to achieve your goals.<br/>
   Do **not** adapt your work to specific tools.
 - Keep track of tools' EOL and keep them updated accordingly.
@@ -67,38 +67,37 @@ What really worked for me.
 - [Branch early, branch often].
 - [Keep a changelog].
 - [Keep changes short and sweet][the art of small pull requests].<br/>
-  Nobody likes to dive deep into a 1200 lines, 356 files pull request ([PR fatigue][how to tackle pull request fatigue],
-  everybody?).
-- Consider keeping changes in _behaviour_ (logic) separated from changes to the structure.<br/>
+  Nobody likes to dive deep into a 1200+ lines, 356+ files pull request
+  ([PR fatigue][how to tackle pull request fatigue], right?).
+- Consider keeping changes in _behaviour_ (logic) separated from changes to the _structure_.<br/>
   It allows for easier debugging by letting you deal with one great issue at a time.
-- Make changes easy, avoid making easy changes.<br/>
-  Easy changes will build up long term and become a pain to deal with.
-- [Trunk-based development][trunk-based development: a comprehensive guide] and other branching strategies all
+- Make changes easy, avoid making _easy changes_.<br/>
+  Easy changes will only build up with time and become a pain to deal with long term.
+- [Trunk-based development][trunk-based development: a comprehensive guide] and other branching strategies **all**
   work.<br/>
   Consider the [different pros and cons of each][git branching strategies vs. trunk-based development].
 - Refactoring _can_ be an option.<br/>
   Just **don't default** to it nor use it mindlessly.
 - Be aware of [corporate bullshit][from inboxing to thought showers: how business bullshit took over].
 - _DevOps_, _GitOps_ and other similar terms are sets of practices, suggestions, or approaches.<br/>
-  They are **not** roles or job titles.<br/>
-  They are **not** to be taken literally.<br/>
+  They should **not** roles or job titles.<br/>
+  They should **not** to be taken literally.<br/>
   They **need** to be adapted to the workplace, not the other way around.
-- [Amazon's leadership principles] are double-edge swords.<br/>
-  They are generally good practices, but only Amazon is able to apply them as they are defined **and** they still create
-  a lot of discontent when used against people.
+- [Amazon's leadership principles] are generally good practices, but also double-edge swords.<br/>
+  They still create a lot of discontent even inside Amazon when used _against_ anybody.
 - Keep Goodhart's law in mind:
   > When a measure becomes a target, it ceases to be a good measure.
 
 ## Teamwork
 
 - Respect what is already there, but strive to improve it.<br/>
-  Current solutions are there for a reason. Learn about their ins and outs **and, most of all, the why**.<br/>
-  Then try to make them better.
+  Current solutions are there for a reason. Learn about their ins and outs **and, most of all, the why**. Only _then_,
+  it makes any sense to try to make them better.
 - Don't just dismiss your teammates' customs.<br/>
   E.g., use [EditorConfig] instead of your editor's specific setting files only.
-- You, your teammates and other teams in your company _should be_ on the same boat and _should be_ shooting for the same
-  goal.<br/>
-  Act like it. You may as well collaborate instead of fighting.
+- One and one's contributors (e.g. one's teammates and other teams in one's company) _should be_ on the same boat and
+  _should be_ shooting for the same goals.<br/>
+  Act like it. You may as well collaborate instead of fighting each other.
 
 ## CI/CD specific
 
@@ -109,32 +108,36 @@ What really worked for me.
 ### Pipelining
 
 - Differentiate what the concept of pipelines really is from the idea of pipelines in approaches like DevOps.<br/>
-  Pipelines are sequences of actions. Pipelines in DevOps and alike end up being magic tools to take actions away from
-  people.
+  Pipelines in general are nothing more than _sequences of actions_. Pipelines in DevOps and alike end up most of the
+  times being _magic tools that take actions away from people_.
 - Keep in mind [the automation paradox].<br/>
-  Pipelines tend to easily become complex systems just like Rube Goldberg machines.
+  Pipelines tend to become complex systems just like Rube Goldberg machines.
 - Keep tasks as simple, consistent and reproducible as possible.<br/>
-  Avoid like the plague to put programs or scripts in pipelines: they should be _glue_, not replace applications.
+  Avoid like the plague relying on programs or scripts written directly in pipelines: pipeline should act as the _glue_
+  connecting tasks, not replace full fledged applications.
 - All tasks should be able to execute from one's own local machine.<br/>
   This allows to fail fast and avoid wasting time waiting for pipelines to run in a black box somewhere.
-- Consider using local automation to guarantee basic quality **before** the code reaches the shared repository.<br/>
-  Tools like [`pre-commit`][pre-commit] or [`lefthook`][lefthook] are a doozy for this.
-- DevOps pipelines are meant to be used as **last mile** steps for specific goals.<br/>
+- DevOps pipelines should be meant to be used as **last mile** steps for specific goals.<br/>
   There **cannot** be a single pipeline for everything, the same way as the _one-size-fits-all_ concept never really
   works.
+- Try and strike a balance between what **needs** to be done centrally (e.g. from a repository's `origin` remote) and
+  what can be done locally from one's machine **before** the code reaches repositories' remotes.<br/>.
+  Tools like [`pre-commit`][pre-commit] or [`lefthook`][lefthook] are a doozy for this, but can disrupt the development
+  experience and encourage the use of the `--no-verify` switch. Actions that need to be enforced (e.g. automatic
+  formatting) are usually worth done only when changes reach the central remote anyways.
 
 ## Product engineering
 
-Consider what follows for infrastructure and platform engineering as well.
+Consider what follows for _infrastructure_ and _platform engineering_ as well.
 
-- Focus on creating things users will want to use.<br/>
+- Focus on creating things users will **want** to use.<br/>
   Tools should solve issues and alleviate pain points, not create additional walls.
-- Focus on small audiences first. Avoid trying appealing lots of users from the beginning.<br/>
-  If you do not have a user base, the product has no reason to exist but your will to create it.
+- Focus on **small** audiences first. Avoid trying appealing lots of users from the very beginning.<br/>
+  If one does not have a user base, one's product has no reason to exist but one's will to create it.
 - Consider and fix users' pain points **before** adding new features.<br/>
-  If users are not happy with your tool they'll try moving away from it, bringing the discussion back to the previous
+  If users are not happy with one's tool they'll try moving away from it, bringing the discussion back to the previous
   point in this list.
-- Avoid creating mindless abstractions, like templates using variables for all their attributes.<br/>
+- Avoid creating mindless abstractions, like templates using variables for _all_ their attributes.<br/>
   Prefer providing one or at most a few simplified solutions that use different
   [adapters or interfaces][what does it mean to program to interfaces?] in the background instead.<br/>
   E.g., check out how [Crossplane] works.