doc: add extra info over ansible watches and reconcile period (#3384)

**Description of the change:**
- add info over reconcilePeriod similar to the sync period attribute of [manager.Options](https://godoc.org/sigs.k8s.io/controller-runtime/pkg/manager#Options) to make clear that users should avoid small periods
- clarifies that users are able to create many CRD's and use the APIs to persuade the concepts such as single responsibility, cohesion and encapsulation which would bring more flexibility and optimization since they are able to do configurations per GKV via the watches file. 

**Motivation for the change:**

#3364

Author: camilamacedo86

website/content/en/docs/ansible/development-tips.md

@@ -187,8 +187,7 @@ the below section for Ansible Operator specific annotations.
 #### Ansible Operator annotations
 This is the list of CR annotations which will modify the behavior of the operator:
 
-**ansible.operator-sdk/reconcile-period**: Used to specify the reconciliation
-interval for the CR. This value is parsed using the standard Golang package
+**ansible.operator-sdk/reconcile-period**: Specifies the maximum time before a reconciliation is triggered. Note that at scale, this can reduce performance, see [watches][watches] reference for more information. This value is parsed using the standard Golang package
 [time][time_pkg]. Specifically [ParseDuration][time_parse_duration] is used
 which will apply the default suffix of `s` giving the value in seconds.
 
@@ -202,6 +201,9 @@ annotations:
   ansible.operator-sdk/reconcile-period: "30s"
 ```
 
+Note that a lower period will correct entropy more quickly, but reduce responsiveness to change 
+if there are many watched resources. Typically, this option should only be used in advanced use cases where `watchDependentResources` is set to `False`  and when is not possible to use the watch feature. E.g To managing external resources that don’t raise Kubernetes events.
+
 ### Testing an Ansible operator locally
 
 Once a developer is comfortable working with the above workflow, it will be
@@ -507,3 +509,4 @@ operator. The `meta` fields can be accesses via dot notation in Ansible as so:
 [manage_status_proposal]:../../proposals/ansible-operator-status.md
 [time_pkg]:https://golang.org/pkg/time/
 [time_parse_duration]:https://golang.org/pkg/time/#ParseDuration
+[watches]:/docs/ansible/reference/watches

website/content/en/docs/ansible/reference/watches.md

@@ -27,8 +27,7 @@ be monitored for updates and cached.
   current project directory.
 * **vars**: This is an arbitrary map of key-value pairs. The contents will be
   passed as `extra_vars` to the playbook or role specified for this watch.
-* **reconcilePeriod** (optional): The reconciliation interval, how often the
-  role/playbook is run, for a given CR.
+* **reconcilePeriod** (optional): The maximum interval in seconds that the operator will wait before beginning another reconcile, even if no watched events are received. When an operator watches many resources, each reconcile can become expensive, and a low value here can actually reduce performance. Typically, this option should only be used in advanced use cases where `watchDependentResources` is set to `False`  and when is not possible to use the watch feature. E.g To managing external resources that don’t raise Kubernetes events.
 * **manageStatus** (optional): When true (default), the operator will manage
   the status of the CR generically. Set to false, the status of the CR is
   managed elsewhere, by the specified role/playbook or in a separate controller.
@@ -122,3 +121,30 @@ Some features can be overridden per resource via an annotation on that CR. The o
     vars:
       state: absent
 ```
+
+**Note:** By using the command `operator-sdk add api` you are able to add additional CRDs to the project API, which can aid in designing your solution using concepts such as encapsulation, single responsibility principle, and cohesion, which could make the project easier to read, debug, and maintain. With this approach, you are able to customize and optimize the configurations more specifically per GKV via the `watches.yaml` file.
+
+**Example:** 
+
+```YaML
+---
+- version: v1alpha1
+  group: app.example.com
+  kind: AppService
+  playbook: playbook.yml
+  maxRunnerArtifacts: 30
+  reconcilePeriod: 5s
+  manageStatus: False
+  watchDependentResources: False
+  finalizer:
+    name: finalizer.app.example.com
+    vars:
+      state: absent
+
+- version: v1alpha1
+  group: app.example.com
+  kind: Database
+  playbook: playbook.yml
+  watchDependentResources: True
+  manageStatus: True
+```