docs: review and improve docs (#1331)

Also simplify WorkflowBuilder.

Co-authored-by: Attila Mészáros <csviri@gmail.com>

Author: metacosm

docs/documentation/architecture-and-internals.md

@@ -7,48 +7,62 @@ permalink: /docs/architecture-and-internals
 
 # Architecture and Internals
 
-This document gives an overview of the internal structure and components of Java Operator SDK core, in order to make it
-easier for developers to understand and contribute to it. However, this is just an extract of the backbone of the core
-module, but other parts should be fairly easy to understand. We will maintain this document on developer feedback.
+This document gives an overview of the internal structure and components of Java Operator SDK core,
+in order to make it easier for developers to understand and contribute to it. This document is
+not intended to be a comprehensive reference, rather an introduction to the core concepts and we
+hope that the other parts should be fairly easy to understand. We will evolve this document
+based on the community's feedback.
 
 ## The Big Picture and Core Components
 
-![Alt text for broken image link](../assets/images/architecture.svg)
+![JOSDK architecture](../assets/images/architecture.svg)
 
-[Operator](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/Operator.java)
+An [Operator](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/Operator.java)
 is a set of
 independent [controllers](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/Controller.java)
-. Controller however, is an internal class managed by the framework itself. It encapsulates directly or indirectly all
-the processing units for a single custom resource. Other components:
+.
+The `Controller` class, however, is an internal class managed by the framework itself and
+usually shouldn't interacted with directly by end users. It
+manages all the processing units involved with reconciling a single type of Kubernetes resource.
 
+Other components include:
+
+- [Reconciler](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/Reconciler.java)
+  is the primary entry-point for the developers of the framework to implement the reconciliation
+  logic.
+- [EventSource](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/EventSource.java)
+  represents a source of events that might eventually trigger a reconciliation.
 - [EventSourceManager](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/EventSourceManager.java)
-  aggregates all the event sources regarding a controller. Provides starts and stops the event sources.
+  aggregates all the event sources associated with a controller. Manages the event sources'
+  lifecycle.
 - [ControllerResourceEventSource](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/controller/ControllerResourceEventSource.java)
-  is a central event source that watches the controller related custom resource for changes, propagates events and
-  caches the state of the custom resources. In the background from V2 it uses Informers.
+  is a central event source that watches the resources associated with the controller (also
+  called primary resources) for changes, propagates events and caches the related state.
 - [EventProcessor](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/EventProcessor.java)
-  processes the incoming events. Implements execution serialization. Manages the executor service for execution. Also
-  implements the post-processing of after the reconciler was executed, like re-schedules and retries of events.
+  processes the incoming events and makes sure they are executed in a sequential manner, that is
+  making sure that the events are processed in the order they are received for a given resource,
+  despite requests being processed concurrently overall. The `EventProcessor` also takes care of
+  re-scheduling or retrying requests as needed.
 - [ReconcilerDispatcher](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/ReconciliationDispatcher.java)
-  is responsible for managing logic around reconciler execution, deciding which method should be called of the
-  reconciler, managing the result
-  (UpdateControl and DeleteControl), making the instructed Kubernetes API calls.
-- [Reconciler](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/Reconciler.java)
-  is the primary entry-point for the developers of the framework to implement the reconciliation logic.
+  is responsible for dispatching requests to the appropriate `Reconciler` method and handling
+  the reconciliation results, making the instructed Kubernetes API calls.
 
 ## Typical Workflow
 
 A typical workflows looks like following:
 
-1. An EventSource produces and event, that is propagated to the event processor.
-2. In the event processor the related `CustomResource` is read from the cache based on the `ResourceID` in the event.
-3. If there is no other execution running for the custom resource, an execution is submitted for the executor (thread
-   pool) .
-4. Executor calls ReconcilerDispatcher which decides which method to execute of the reconciler. Let's say in this case it
-   was `reconcile(...)`
-5. After reconciler execution the Dispatcher calls Kubernetes API server, since the `reconcile` method returned
-   with `UpdateControl.patchStatus(...)` result.
-6. Now the dispatcher finishes the execution and calls back `EventProcessor` to finalize the execution.
-7. EventProcessor checks if there is no `reschedule` or `retry` required and if there are no subsequent events received
-   for the custom resource
-8. Neither of this happened, therefore the event execution finished.
+1. An `EventSource` produces an event, that is propagated to the `EventProcessor`.
+2. The resource associated with the event is read from the internal cache.
+3. If the resource is not already being processed, a reconciliation request is
+   submitted to the executor service to be executed in a different thread, encapsulated in a
+   `ControllerExecution` instance.
+4. This, in turns, calls the `ReconcilerDispatcher` which dispatches the call to the appropriate
+   `Reconciler` method, passing along all the required information.
+5. Once the `Reconciler` is done, what happens depends on the result returned by the
+   `Reconciler`. If needed, the `ReconcilerDispatcher` will make the appropriate calls to the
+   Kubernetes API server.
+6. Once the `Reconciler` is done, the `EventProcessor` is called back to finalize the
+   execution and update the controller's state.
+7. The `EventProcessor` checks if the request needs to be rescheduled or retried and if there are no
+   subsequent events received for the same resource.
+8. When none of this happens, the processing of the event is finished. 

docs/documentation/contributing.md

@@ -4,10 +4,12 @@ description: Contributing To Java Operator SDK
 layout: docs
 permalink: /docs/contributing
 ---
+
 # Contributing To Java Operator SDK
 
-Firstly, big thanks for considering contributing to the project. We really hope to make this into a
-community project and to do that we need your help!
+First of all, we'd like to thank you for considering contributing to the project! We really
+hope to create a vibrant community around this project but this won't happen without help from
+people like you!
 
 ## Code of Conduct
 
@@ -16,21 +18,24 @@ aggressive or insulting behaviour.
 
 To this end, the project and everyone participating in it is bound by the [Code of
 Conduct]({{baseurl}}/coc). By participating, you are expected to uphold this code. Please report
-unacceptable behaviour to any of the project admins or adam.sandor@container-solutions.com.
+unacceptable behaviour to any of the project admins.
 
 ## Bugs
 
-If you find a bug, please [open an issue](https://github.com/java-operator-sdk/java-operator-sdk/issues)! Do try
+If you find a bug,
+please [open an issue](https://github.com/java-operator-sdk/java-operator-sdk/issues)! Do try
 to include all the details needed to recreate your problem. This is likely to include:
 
- - The version of the Operator SDK being used
- - The exact platform and version of the platform that you're running on
- - The steps taken to cause the bug
+- The version of the Operator SDK being used
+- The exact platform and version of the platform that you're running on
+- The steps taken to cause the bug
+- Reproducer code is also very welcome to help us diagnose the issue and fix it quickly
 
 ## Building Features and Documentation
 
 If you're looking for something to work on, take look at the issue tracker, in particular any items
-labelled [good first issue](https://github.com/java-operator-sdk/java-operator-sdk/labels/good%20first%20issue).
+labelled [good first issue](https://github.com/java-operator-sdk/java-operator-sdk/labels/good%20first%20issue)
+.
 Please leave a comment on the issue to mention that you have started work, in order to avoid
 multiple people working on the same issue.
 
@@ -42,18 +47,19 @@ discussing it first to avoid wasting effort. We do commit to listening to all pr
 our best to work something out!
 
 Once you've got the go ahead to work on a feature, you can start work. Feel free to communicate with
-team via updates on the issue tracker or the [Discord channel](https://discord.gg/DacEhAy) and ask for feedback, pointers etc.
-Once you're happy with your code, go ahead and open a Pull Request.
+team via updates on the issue tracker or the [Discord channel](https://discord.gg/DacEhAy) and ask
+for feedback, pointers etc. Once you're happy with your code, go ahead and open a Pull Request.
 
 ## Pull Request Process
 
-First, please format your commit messages so that they follow the [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) format.
+First, please format your commit messages so that they follow
+the [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) format.
 
 On opening a PR, a GitHub action will execute the test suite against the new code. All code is
-required to pass the tests, and new code must be accompanied by new tests. 
+required to pass the tests, and new code must be accompanied by new tests.
 
-All PRs have to be reviewed and signed off by another developer before being merged to the master
-branch. This review will likely ask for some changes to the code - please don't be alarmed or upset
+All PRs have to be reviewed and signed off by another developer before being merged. This review
+will likely ask for some changes to the code - please don't be alarmed or upset
 at this; it is expected that all PRs will need tweaks and a normal part of the process.
 
 The PRs are checked to be compliant with the Java Google code style.
@@ -64,12 +70,15 @@ Be aware that all Operator SDK code is released under the [Apache 2.0 licence](L
 
 ### Code style
 
-The SDK modules and samples are formatted to follow the Java Google code style. 
-On every `compile` the code gets formatted automatically, 
-however, to make things simpler (i.e. avoid getting a PR rejected simply because of code style issues), you can import one of the following code style schemes based on the IDE you use:
+The SDK modules and samples are formatted to follow the Java Google code style.
+On every `compile` the code gets formatted automatically, however, to make things simpler (i.e.
+avoid getting a PR rejected simply because of code style issues), you can import one of the
+following code style schemes based on the IDE you use:
 
-- for *Intellij IDEA* import [contributing/intellij-google-style.xml](contributing/intellij-google-style.xml)
-- for *Eclipse* import [contributing/eclipse-google-style.xml](contributing/eclipse-google-style.xml)
+- for *Intellij IDEA*
+  import [contributing/intellij-google-style.xml](contributing/intellij-google-style.xml)
+- for *Eclipse*
+  import [contributing/eclipse-google-style.xml](contributing/eclipse-google-style.xml)
 
 ## Thanks