Improve docs for manager.Options.SyncPeriod

The comment tries to capture more of the thoughts exchanged in
kubernetes-sigs#88.

Author: dlipovetsky

pkg/manager/manager.go

@@ -139,6 +139,20 @@ type Options struct {
 	// value only if you know what you are doing. Defaults to 10 hours if unset.
 	// there will a 10 percent jitter between the SyncPeriod of all controllers
 	// so that all controllers will not send list requests simultaneously.
+	//
+	// A period sync happens for two reasons:
+	// 1. To insure against your controller not requeueing an object.
+	// 2. To insure against controller-runtime, or its dependencies, failing to
+	// requeue an object, or inadvertently removing it from the requeue.
+	//
+	// If you want
+	// 1. to insure against missed watch events, or
+	// 2. to poll services that cannot be watched,
+	// then we recommend that, instead of setting a shorter sync period, your
+	// controller requeue with a constant duration whenever it is "done," and
+	// would otherwise not requeue, i.e., we recommend your reconcile loop
+	// return `reconcile.Result{RequeueAfter: t}`, instead of
+	// `reconcile.Result{}`.
 	SyncPeriod *time.Duration
 
 	// Logger is the logger that should be used by this manager.