Consider removing docs on tweaking zone configs for system ranges

[rmloveland]

Richard Loveland (rmloveland) commented:

Currently (Thursday, April 22, 2021), we have docs on tweaking the zone configs for system ranges.

We may want to reconsider having this in public docs. It seems like a potential footgun that most users probably shouldn't use (please correct me if I'm wrong). We seem to acknowledge this with a note that says "hey you might break your system if you mess this up". We say "use caution" but it's not clear how one would know how to apply caution in this situation unless they already have expertise in this area?

My argument for removing this from docs is the fact that a process being publicly documented sends an implicit message "hey, it's perfectly ok to do this if you want". Perhaps I am misunderstanding something, but this seems like something that should probably only be done if you are working directly with someone from CRL with expertise who is telling you to do this in a support- or experts-doing-perf-tuning type of interaction.

Jira Issue: DOC-1622

[rmloveland]

@mwang1026 I think this falls into KV PM territory (please let me know if not). Do you have opinions?

[mwang1026]

Do you have a sense of why we added it in the first place? What was it for and who we intended to use it?

[mwang1026]

I guess asked another way -- will we still expose them if we DON'T document it? And if so will that confuse users or make the situation worse? What's the outcome we want?

I agree tweaking the system zone configs could be -- hairy.

[rmloveland]

Michael Wang @.***> writes:

Do you have a sense of why we added it in the first place? What was it for and who we intended to use it?

It appears to have been added in cockroachdb/docs#2965, way back in

2018. The associated PR (https://github.com/cockroachdb/docs/pull/3884) has a lot of info on zone configs in general, but was not about this feature specifically.

Funnily enough I asked about this in my review as well back then, but did not push for an answer, unfortunately. :-}

I guess asked another way -- will we still expose them if we DON'T document it? And if so will that confuse users or make the situation worse? What's the outcome we want?

Historically we documented (seemingly) everything, even things that were hairy or dangerous.

We've somewhat moved away from that more recently, e.g. we now have some cluster settings that are not visible by default via SHOW CLUSTER SETTINGS.

Re: this particular issue, I think the situation gets better for 99.9% of users if this is not in the docs for the average user to footgun themselves with. But I'll be curious if the engineering team has a different perspective.

Maybe I'll bring this up in the #kv channel or the team meeting? What do you think?

[mwang1026]

I think getting KV team's input is valuable here. No strong feelings on #kv vs team meeting

[github-actions[bot]]

We have marked this issue as stale because it has been inactive for 18 months. If this issue is still relevant, removing the stale label or adding a comment will keep it active. Otherwise, we'll close it in 10 days to keep the issue queue tidy. Thank you for your contribution to CockroachDB docs!