scorecard2 update custom test documentation
@@ -188,7 +188,59 @@ operator-sdk alpha scorecard bundle/ --selector=suite=custom -o json --wait-time
**Note**: More details on the usage of `operator-sdk alpha scorecard` command and its flags can be found in the [scorecard user documentation][user_doc]
-[docker_tool]: https://docs.docker.com/install/
+### Debugging scorecard custom tests
+
+The `--skip-cleanup` flag can be used when executing the `operator-sdk alpha scorecard` command to cause the scorecard created test pods to be unremoved.
+This is useful when debugging or writing new tests so that you can view
+the test logs or the pod manifests.
+
+### Scorecard initContainer
+
+The scorecard inserts an `initContainer` into the test pods it creates. The
+`initContainer` serves the purpose of uncompressing the operator bundle
+contents, mounting them into a shared mount point accessible by test
+images. The operator bundle contents are stored within a ConfigMap, uniquely
+built for each scorecard test execution. Upon scorecard completion,
+the ConfigMap is removed as part of normal cleanup, along with the test
+pods created by scorecard.
+
+### Using Custom Service Accounts
+
+Scorecard does not deploy service accounts, RBAC resources, or
+namespaces for your test but instead considers these resources
+to be outside its scope. You can however implement whatever
+service accounts your tests require and then specify
+that service account from the command line using the service-account flag:
+```
+operator-sdk alpha scorecard --service-account=mycustomsa
+```
+
+Also, you can set up a non-default namespace that your tests
+will be executed within using the following namespace flag:
+```
+operator-sdk alpha scorecard --namespace=mycustomns
+```
+
+If you do not specify either of these flags, the default namespace
+and service account will be used by the scorecard to run test pods.
+
+### Returning Multiple Test Results
+
+Some custom tests might require or be better implemented to return
+more than a single test result. For this case, scorecard's output
+API allows multiple test results to be defined for a single test. See
+https://github.com/operator-framework/operator-sdk/blob/master/pkg/apis/scorecard/v1alpha3/types.go#L59
+
+### Accessing the Kube API
+
+Within your custom tests you might require connecting to the Kube API.
+In golang, you could use the [client-go][client_go] API for example to
+check Kube resources within your tests, or even create custom resources. Your
+custom test image is being executed within a Pod, so you can use an in-cluster
+connection to invoke the Kube API.
+
+
+[client_go]: https://github.com/kubernetes/client-go
[olm_tests]: https://github.com/operator-framework/operator-sdk/blob/master/internal/scorecard/alpha/tests/olm.go
[basic_tests]: https://github.com/operator-framework/operator-sdk/blob/master/internal/scorecard/alpha/tests/basic.go
[config_yaml]: https://github.com/operator-framework/operator-sdk/blob/master/internal/scorecard/alpha/testdata/bundle/tests/scorecard/config.yaml
