📖 [Docs] Reorganize developer documentation (#1279)

* Reorganize developer documentation

Reordered sections and added MacOS setup into a dedicated section. Improved structure for better readability and provided clear instructions for installing and using necessary tools.

Signed-off-by: Brett Tofel <[email protected]>

* Incorporate trgeiger comments

Signed-off-by: Brett Tofel <[email protected]>

* Remove How-to; clarify Kind use; grammar

Signed-off-by: Brett Tofel <[email protected]>

* Fix missing backticks

Signed-off-by: Brett Tofel <[email protected]>

---------

Signed-off-by: Brett Tofel <[email protected]>

Author: bentito

docs/drafts/developer.md

@@ -1,10 +1,24 @@
+
 ## Getting Started
-You’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster.
+
+The following `make run` starts a [KIND](https://sigs.k8s.io/kind) cluster for you to get a local cluster for testing, see the manual install steps below for how to run against a remote cluster.
 
 > [!NOTE]
 > Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows).
+> 
+> If you are on MacOS, see [Special Setup for MacOS](#special-setup-for-macos).
+
+### Quickstart Installation
+
+First, you need to install the CRDs and the operator-controller into a new [KIND cluster](https://kind.sigs.k8s.io/). You can do this by running:
+
+```sh
+make run
+```
+
+This will build a local container image of the operator-controller, create a new KIND cluster and then deploy onto that cluster. This will also deploy the catalogd and cert-manager dependencies.
 
-### Installation
+### To Install Any Given Release
 
 > [!CAUTION]  
 > Operator-Controller depends on [cert-manager](https://cert-manager.io/). Running the following command
@@ -16,27 +30,7 @@ The latest version of Operator Controller can be installed with the following co
 curl -L -s https://github.com/operator-framework/operator-controller/releases/latest/download/install.sh | bash -s
 ```
 
-### Additional setup on Macintosh computers
-On Macintosh computers some additional setup is necessary to install and configure compatible tooling.
-
-#### Install Homebrew and tools
-Follow the instructions to [installing Homebrew](https://docs.brew.sh/Installation) and then execute the following to install tools:
-
-```sh
-brew install bash gnu-tar gsed
-```
-
-#### Configure your shell
-Modify your login shell's `PATH` to prefer the new tools over those in the existing environment.  This example should work either with `zsh` (in $HOME/.zshrc) or `bash` (in $HOME/.bashrc):
-
-```sh
-for bindir in `find $(brew --prefix)/opt -type d -follow -name gnubin -print`
-do
-  export PATH=$bindir:$PATH
-done
-```
-
-### Running on the cluster
+### Manual Step-by-Step Installation
 1. Install Instances of Custom Resources:
 
 ```sh
@@ -69,33 +63,20 @@ To undeploy the controller from the cluster:
 make undeploy
 ```
 
-### How it works
-This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/).
-
-It uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/)
-which provide a reconcile function responsible for synchronizing resources until the desired state is reached on the cluster.
-
-### Test It Out
-
-Install the CRDs and the operator-controller into a new [KIND cluster](https://kind.sigs.k8s.io/):
-```sh
-make run
-```
-This will build a local container image of the operator-controller, create a new KIND cluster and then deploy onto that cluster.
-This will also deploy the catalogd and cert-manager dependencies.
-
 ### Modifying the API definitions
 If you are editing the API definitions, generate the manifests such as CRs or CRDs using:
 
 ```sh
 make manifests
 ```
 
+---
+
 **NOTE:** Run `make help` for more information on all potential `make` targets.
 
-### Rapid iterative development with Tilt
+### Rapid Iterative Development with Tilt
 
-If you are developing against the combined ecosystem of catalogd + operator-controller you will want to take advantage of `tilt`:
+If you are developing against the combined ecosystem of catalogd + operator-controller, you will want to take advantage of `tilt`:
 
 [Tilt](https://tilt.dev) is a tool that enables rapid iterative development of containerized workloads.
 
@@ -105,8 +86,6 @@ Here is an example workflow without Tilt for modifying some source code and test
 2. Build the container image.
 3. Either push the image to a registry or load it into your kind cluster.
 4. Deploy all the appropriate Kubernetes manifests for your application.
-    1. Or, if this is an update, you'd instead scale the Deployment to 0 replicas, scale back to 1, and wait for the
-       new pod to be running.
 
 This process can take minutes, depending on how long each step takes.
 
@@ -125,9 +104,7 @@ Follow Tilt's [instructions](https://docs.tilt.dev/install.html) for installatio
 ### Installing catalogd
 
 operator-controller requires
-[catalogd](https://github.com/operator-framework/catalogd). Please make sure it's installed, either normally or via
-their own Tiltfiles, before proceeding. If you want to use Tilt, make sure you specify a unique `--port` flag to each
-`tilt up` invocation.
+[catalogd](https://github.com/operator-framework/catalogd). Please make sure it's installed, either normally or via its own Tiltfile., before proceeding. If you want to use Tilt, make sure you specify a unique `--port` flag to each `tilt up` invocation.
 
 ### Install tilt-support Repo
 
@@ -171,25 +148,33 @@ v0.33.1, built 2023-06-28
 (ctrl-c) to exit
 ```
 
-Typically, you'll want to press the space bar to have it open the UI in your web browser.
+At the end of the installation process, the command output will prompt you to press the space bar to open the web UI, which provides a useful overview of all the installed components.
+
+---
+
+## Special Setup for MacOS
+
+Some additional setup is necessary on Macintosh computers to install and configure compatible tooling.
 
-Shortly after starting, Tilt processes the `Tiltfile`, resulting in:
+### Install Homebrew and tools
+Follow the instructions to [install Homebrew](https://docs.brew.sh/Installation), and then execute the following command to install the required tools:
 
-- Building the go binaries
-- Building the images
-- Loading the images into kind
-- Running kustomize and applying everything except the Deployments that reference the images above
-- Modifying the Deployments to use the just-built images
-- Creating the Deployments
+```sh
+brew install bash gnu-tar gsed
+```
 
-### Making code changes
+### Configure your shell
+To configure your shell, either add this to your bash or zsh profile (e.g., in $HOME/.bashrc or $HOME/.zshrc), or run the following command in the terminal:
 
-Any time you change any of the files listed in the `deps` section in the `<binary name>_binary` `local_resource`,
-Tilt automatically rebuilds the go binary. As soon as the binary is rebuilt, Tilt pushes it (and only it) into the
-appropriate running container, and then restarts the process.
+```sh
+for bindir in `find $(brew --prefix)/opt -type d -follow -name gnubin -print`
+do
+  export PATH=$bindir:$PATH
+done
+```
 
 ---
 
 ## Contributing
 
-Refer to [CONTRIBUTING.md](./CONTRIBUTING.md) for more information.
+Refer to [CONTRIBUTING.md](./CONTRIBUTING.md) for more information.