Repository: kubernetes-sigs/kubebuilder (language: go)

Issue:
Doc: add info about markers
### What do you want to happen?

This task is for we add the clarification made in https://kubernetes.slack.com/archives/CAR30FCJZ/p1645546692768789 about what is the diff between  `// +optional` and `// +kubebuilder:validation:Optional` to the docs. Also, see: https://kubernetes.slack.com/archives/CAR30FCJZ/p1561671375059100?thread_ts=1561635781.050000&cid=CAR30FCJZ

It might fit well as a note in the : https://book.kubebuilder.io/reference/markers.html

### Extra Labels

/kind documentation


Discussion / hints:
/assign
But can you tell which particular doc should reflect the changes?
@sayantani11 Just adding a note to [markers](https://book.kubebuilder.io/reference/markers.html) should suffice. 
You can check an example of note in the quick start. It is like :

```
<aside class="note">
<h1>Title</h1>

Content

</aside>
```

Fix patch:
diff --git a/docs/book/src/reference/markers.md b/docs/book/src/reference/markers.md
index 1d5fdfd778f..88a23e33624 100644
--- a/docs/book/src/reference/markers.md
+++ b/docs/book/src/reference/markers.md
@@ -15,6 +15,19 @@ a marker name, optionally followed by some marker specific configuration:
 // +kubebuilder:printcolumn:JSONPath=".status.replicas",name=Replicas,type=string
 ```
 
+<aside class="note">
+<h1>difference between `// +optional` and `// +kubebuilder:validation:Optional`</h1>
+
+ Controller-gen supports both (see the output of `controller-gen crd -www`). `+kubebuilder:validation:Optional` and `+optional` can be applied to fields.
+
+ But `+kubebuilder:validation:Optional` can also be applied at the package level such that it applies to every field in the package.
+
+ If you're using controller-gen only then they're redundant, but if you're using other generators or you want developers that need to  build their own clients for your API, you'll want to also include `+optional`.
+
+ The most reliable way in 1.x to get `+optional` is `omitempty`.
+
+</aside>
+
 See each subsection for information about different types of code and YAML
 generation.
 


Test patch: