Proposal: Restructuring Kubernetes Operator Documentation

[makasim]

This proposal suggests reorganizing the Kubernetes Operator documentation to enhance clarity, usability, and discoverability of information. The new structure aims to provide a more intuitive navigation experience for users of all levels. Naming conventions will be finalized based on feedback.

Proposed Documentation Structure

Kubernetes Operator
├── Quick Start
├── Installation
├── Configuration
├── Resources
│   ├── Reference
│   ├── VMSingle
│   ├── VMCluster
│   ├── ....
│   └── VMAlert
├── Integrations
│   ├── Grafana
│   ├── Prometheus
│   └── Istio
├── Enterprise
├── Troubleshooting
├── Development
└── CHANGELOG

To ensure a smooth transition and preserve backward compatibility:

• Old documentation URLs or anchor points will include clear notices such as "Moved to..."
• Redirects will be implemented where appropriate and where they do not cause significant disruption

Current sections migration:

• Setup will be transformed into Installation
• Security will become part of Configuration
• Migration from Prometheus will become part of Integrations -> Prometheus
• Monitoring will become part of Configuration
• Authorization and exposing components - TBD (leave at the top or move to configuration).
• FAQ - will be split between Configuration, Troubleshooting, and resource pages.
• Variables will become part of Configuration
• API Docs will become Resource subpage Reference
• Custom resources subpages will be renamed to Resources.
• Release guidance will become part of Development.

The restructuring will be implemented incrementally through a series of separate pull requests (PRs).

[makasim]

@hagen1778 @valyala @tenmozes fyi

[valyala]

The proposed structure of the docs looks good. Please take especial care to don't break the existing urls, since they may exist all over the Internet, and they should continue working and providing the originally linked information. Additional click to Moved to ... link is OK. It is better than the automatic redirect via JavaScript in general case, since automatic redirect breaks "backwards" navigation in browsers. "Backwards" navigation is frequently used when clicking links at the external source, reading our docs and then clicking "back" button in the web browser for returning to the original place at the external source.

[tenmozes]

It looks good and follows the concepts of VictoriaMetrics documentation; however, the unique part of the operator is Kubernetes, and I believe we need to pay more attention to K8S specific entities. Could you please verify how often people check what is VMPodScrape, VMRule, etc vs VMalert, VMSingle?

[Amper]

Hey, I'm not sure about:

Migration from Prometheus will become part of Integrations -> Prometheus

I don't think that integration and migration the same things. Maybe we should add section "Migration" here, because it will be great to have "Migration from X" articles here (Mimir, Influx, etc....).

[makasim]

@Amper I'm thinking of "integrations" in broad terms — to separate documentation purely about VictoriaMetrics from documentation involving third parties. The involvement with these 3rd parties can vary widely and isn't limited to the classic definition of "integration" like calling an external API.

In this context, migration is just one type of integration. Basically, anything that's not purely about VictoriaMetrics itself could live under an "Integrations" section.

I believe this simplifies the user experience, too. Once users understand the logic behind the "Integrations" concept, it's much easier for them to find related content. For example, All stuff related to how VictoriaMetrics works (dare I say integrates) with Grafana goes to operator/integrations/grafana page.

@hagen1778 would like to hear your opinion

[makasim]

Could you please verify how often people check what is VMPodScrape, VMRule, etc vs VMalert, VMSingle?

@tenmozes here's the top 3 resource pages:

• /operator/resources/vmagent/
• /operator/resources/vmservicescrape/
• /operator/resources/vmalertmanager/

Overall top 3 operator pages:

• /operator/api/
• /operator/resources/vmagent/
• /operator/quick-start/

[tenmozes]

Should we focus on the solutions' names or the problems they solve?

[hagen1778]

├── VMSingle
├── VMCluster
├── VMAlert
├── ...

How many CRDs will it have eventually? I ask because I don't like long navigation bars. I hate our left navigation bar at https://docs.victoriametrics.com/:

If we're going to revamp operator docs, I'd like to avoid this mistake there.

[hagen1778]

Maybe we should add section "Migration" here, because it will be great to have "Migration from X" articles here (Mimir, Influx, etc....).

I know this sounds good, because migration is a hot topic, a common thing everyone is looking for. But following this logic we achieved super-bulky polluted documentation at https://docs.victoriametrics.com/victoriametrics/single-server-victoriametrics/. I would like to keep the structure concise instead of including "hot" items in the navigation for user convenience.

To correct myself, I am not against having Migration as a menu bullet. If you all think Migration is something that stays with us forever and is of constant interest, now and then, then have it as a menu bullet.

[makasim]

I know this sounds good, because migration is a hot topic, a common thing everyone is looking for. But following this logic we achieved super-bulky polluted documentation at https://docs.victoriametrics.com/victoriametrics/single-server-victoriametrics/. I would like to keep the structure concise instead of including "hot" items in the navigation for user convenience.

I'd mention it where appropriate throughout the documentation, such as at the beginning of the Quick Start (e.g., “If you have Prometheus installed, check out the migration guide”), while still keeping it listed under Integrations.

The reasoning is that users migrating from Prometheus will likely go through the installation or Quick Start sections first, whereas those already familiar with VictoriaMetrics will follow the "Integrations" convention and head directly there for Prometheus/VictoriaMetrics-related setup and migration details.

[makasim]

How many CRDs will it have eventually? I ask because I don't like long navigation bars. I hate our left navigation bar at https://docs.victoriametrics.com/:

Currently, we have 14 resources for VictoriaMetrics and 2 for VictoriaLogs. Honestly, I am not 100% sure we should move resources to the top. So, I'll explore other options.

[makasim]

I've updated the description. There is a new section called Resources. It will contain Reference (currently API Docs) and all resource-specific pages. Please take a look at the issue description.

[makasim]

Added new section Development. Release guidance will become part of it.