docs: samples facelift (#784)

Author: csviri

docs/documentation/getting-started.md

@@ -38,60 +38,5 @@ to the cluster. This is why it was important to set up kubectl up front.
 1. Verify if the operator is up and running. Don't run it locally anymore to avoid conflicts in processing events from 
 the cluster's API server.
 
-## Controllers
-Controllers are where you implement the business logic of the Operator. An Operator can host multiple Controllers, 
-each handling a different type of Custom Resource. In our samples each Operator has a single Controller. 
 
-[comment]: <> (## Automatic Retries)
 
-[comment]: <> (## Running The Operator)
-
-[comment]: <> (## Development Tips & Tricks)
-
-[comment]: <> (TODO: explain running operator locally against a cluster)
-
-[comment]: <> (## Event Processing Details)
-
-[comment]: <> (### Handling Finalizers)
-
-[comment]: <> (### Managing Consistency)
-
-[comment]: <> (### Event Scheduling)
-
-[comment]: <> (### Event Dispatching )
-
-[comment]: <> (### Generation Awareness)
-
-## Dealing with Consistency 
-
-### Run Single Instance
-
-There should be always just one instance of an operator running at a time (think process). If there would be 
-two ore more, in general it could lead to concurrency issues. Note that we are also doing optimistic locking when we update a resource.
-In this way the operator is not highly available. However for operators this is not necessarily an issue, 
-if the operator just gets restarted after it went down. 
-
-### At Least Once
-
-To implement controller logic, we have to override two methods: `createOrUpdateResource` and `deleteResource`. 
-These methods are called if a resource is created/changed or marked for deletion. In most cases these methods will be
-called just once, but in some rare cases, it can happen that they are called more then once. In practice this means that the 
-implementation needs to be **idempotent**.    
-
-### Smart Scheduling
-
-In our scheduling algorithm we make sure, that no events are processed concurrently for a resource. In addition we provide
-a customizable retry mechanism to deal with temporal errors.
-
-### Operator Restarts
-
-When an operator is started we got events for every resource (of a type we listen to) already on the cluster. Even if the resource is not changed 
-(We use `kubectl get ... --watch` in the background). This can be a huge amount of resources depending on your use case.
-So it could be a good case to just have a status field on the resource which is checked, if there is anything needed to be done.
-
-### Deleting a Resource
-
-During deletion process we use [Kubernetes finalizers](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/#finalizers 
-"Kubernetes docs"). This is required, since it can happen that the operator is not running while the delete 
-of resource is executed (think `oc delete`). In this case we would not catch the delete event. So we automatically add a
-finalizer first time we update the resource if it's not there. 

docs/documentation/patterns-best-practices.md

@@ -10,7 +10,7 @@ permalink: /docs/patterns-best-practices
 This document describes patters and best practices, to build and run operators, and how to implement them in terms
 of Java Operator SDK.
 
-## Implementing a Controller
+## Implementing a Reconciler
 
 ### Idempotency
 

docs/documentation/use-samples.md

@@ -5,20 +5,26 @@ layout: docs
 permalink: /docs/using-samples
 ---
 
-# How to use sample Operators
+# Sample Operators we Provide
 
-We have several sample Operators under
-the [samples](https://github.com/java-operator-sdk/java-operator-sdk/tree/master/smoke-test-samples) directory:
+We have few simple Operators under
+the [smoke-test-samples](https://github.com/java-operator-sdk/java-operator-sdk/tree/master/smoke-test-samples) directory.
+These are used mainly to showcase some minimal operators, but also to do some sanity checks during development:
 
 * *pure-java*: Minimal Operator implementation which only parses the Custom Resource and prints to stdout. Implemented
   with and without Spring Boot support. The two samples share the common module.
 * *spring-boot-plain*: Sample showing integration with Spring Boot.
 
-There are also more samples in the standalone [samples repo](https://github.com/java-operator-sdk/samples):
+In addition to that, there are examples under [sample-operators](https://github.com/java-operator-sdk/java-operator-sdk/tree/master/sample-operators)
+directory which are intended to show usage of different components in different scenarios, but mainly are more real world
+examples:
 
-* *webserver*: Simple example creating an NGINX webserver from a Custom Resource containing HTML code.
-* *mysql-schema*: Operator managing schemas in a MySQL database.
-* *tomcat*: Operator with two controllers, managing Tomcat instances and Webapps for these.
+* *webpage*: Simple example creating an NGINX webserver from a Custom Resource containing HTML code.
+* *mysql-schema*: Operator managing schemas in a MySQL database. Shows how to manage non Kubernetes resources.
+* *tomcat*: Operator with two controllers, managing Tomcat instances and Webapps running in Tomcat. The intention 
+  with this example to show how to manage multiple related custom resources and/or more controllers.
+
+# Implementing a Sample Operator
 
 Add [dependency](https://search.maven.org/search?q=a:operator-framework) to your project with Maven:
 
@@ -59,7 +65,7 @@ The Controller implements the business logic and describes all the classes neede
 ```java
 
 @ControllerConfiguration
-public class WebServerController implements Reconciler<WebServer> {
+public class WebPageReconciler implements Reconciler<WebPage> {
 
     // Return the changed resource, so it gets updated. See javadoc for details.
     @Override
@@ -77,9 +83,8 @@ A sample custom resource POJO representation
 
 @Group("sample.javaoperatorsdk")
 @Version("v1")
-public class WebServer extends CustomResource<WebServerSpec, WebServerStatus> implements
+public class WebPage extends CustomResource<WebPageSpec, WebPageStatus> implements
         Namespaced {
-
 }
 
 public class WebServerSpec {
@@ -107,7 +112,7 @@ might want to skip this step. This is done by setting the `CHECK_CRD_ENV_KEY` en
 ### Automatic generation of CRDs
 
 To automatically generate CRD manifests from your annotated Custom Resource classes, you only need to add the following
-dependencies to your project:
+dependencies to your project (in the background an annotation processor is used), with Maven:
 
 ```xml
 
@@ -118,6 +123,15 @@ dependencies to your project:
 </dependency>
 ```
 
+or with Gradle:
+
+```groovy
+dependencies {
+    annotationProcessor 'io.fabric8:crd-generator-apt:<version>'
+    ...
+}
+```
+
 The CRD will be generated in `target/classes/META-INF/fabric8` (or in `target/test-classes/META-INF/fabric8`, if you use
 the `test` scope) with the CRD name suffixed by the generated spec version. For example, a CR using
 the `java-operator-sdk.io` group with a `mycrs` plural form will result in 2 files: