Minor improvements in documentation

grzywin commented 3 months ago

What should the feature do?

As someone relatively new to Kubernetes and Operator, I was attempting to configure a cluster using the instructions provided in the official Operator documentation. During this process, I encountered some minor issues and inconsistencies.

https://operator.docs.scylladb.com/stable/generic.html

[ ] In the prerequisites, it mentions "A Storage Class to provision PersistentVolumes." Why not include steps to create a Storage Class (SC) and Persistent Volume (PV) in the documentation, as already done here with the local CSI driver and XFS volume?
[ ] Helm 3 is listed as a prerequisite, but it’s not used anywhere on the generic.html page. Why is it included?
[ ] The example output of the command kubectl -n scylla get pods shows that each Scylla pod should have 2/2 containers ready, but in reality, it’s 3/3 (manager agent, Scylla, and Scylla operator).
[ ] Is the "Configure host networking" section outdated?
[ ] Connecting to the cluster using the Python Cassandra driver doesn't work as straightforwardly as suggested by the instructions. Why not include information on NodePort configuration or a simple example of the port-forwarding command?
[ ] The --dry-run command was deprecated and should be replaced with --dry-run=client in the command: kubectl create configmap scylla-config -n scylla --from-file=/tmp/scylla.yaml --from-file=/tmp/cassandra-rackdc.properties -o yaml --dry-run | kubectl replace -f -.
[ ] In the "Benchmark with cassandra-stress" section, the commands kubectl apply -f scripts/cassandra-stress.yaml and kubectl delete -f scripts/cassandra-stress.yaml refer to a file located in the hack folder. The correct command should be -f hack/cassandra-stress.yaml.

https://operator.docs.scylladb.com/stable/monitoring.html

[ ] The $ sign could be removed from some commands in the monitoring section, as it’s done in generic.html, to allow users to easily copy and paste the command content.
[ ] The Scylla namespace (-n scylla) is missing from the commands in the "Waiting for ScyllaDBMonitoring to roll out," "Waiting for Prometheus to roll out," and "Waiting for Grafana to roll out" sections. The Scylla namespace is provided everywhere else.
[ ] In the ScyllaDBMonitoring manifest, there is a line 'scylla/cluster: replace-with-your-scyllacluster-name'. Since most newcomers will work with default values, why not replace it with 'scylla/cluster: simple-cluster # replace-with-your-scyllacluster-name'?
[ ] As a rookie, I struggled to connect to Grafana by following the instructions in the "Accessing Grafana" chapter. Why not add a way to connect to Grafana through a web browser, either by using NodePort or by executing the port-forward command?

Most of these points are trivial, and if there are plans to rewrite the documentation, they can probably be discarded. However, I believe it’s important to acknowledge what might challenge newcomers.

What is the use case behind this feature?

Improve user experience.

Anything else we need to know?

No response

scylla-operator-bot[bot] commented 2 months ago

The Scylla Operator project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

After 30d of inactivity, lifecycle/stale is applied
After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

Mark this issue as fresh with /remove-lifecycle stale
Close this issue with /close
Offer to help out

/lifecycle stale

scylla-operator-bot[bot] commented 1 month ago

The Scylla Operator project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

After 30d of inactivity, lifecycle/stale is applied
After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

Mark this issue as fresh with /remove-lifecycle stale
Close this issue with /close
Offer to help out

/lifecycle stale

tnozicka commented 1 month ago

/remove-lifecycle stale

scylla-operator-bot[bot] commented 1 week ago

The Scylla Operator project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

After 30d of inactivity, lifecycle/stale is applied
After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

Mark this issue as fresh with /remove-lifecycle stale
Close this issue with /close
Offer to help out

/lifecycle stale

scylladb / scylla-operator