cluster settings - general page utility

Stephanie Bodoff commented:

Regarding the page itself:

• Is the page useful? What analytics do we have for it?
• Can it be used by serverless users?
• The descriptions are written by engineers and often not very helpful and with poor style. Shouldn't we just discuss the settings we expect users to set in the places where we discuss the reason why you would set them?
• It's the analog of https://www.cockroachlabs.com/docs/dev/functions-and-operators.html.

Personally I've come to doubt the utility of these manually created and generated index pages. Like book indexes, such index pages have marginal utility in the age of search.

Jira Issue: DOC-1702

Epic Im

[jseldess]

Thank you for the great questions, @stbof. I agree entirely with:

Shouldn't we just discuss the settings we expect users to set in the places where we discuss the reason why you would set them?

That said, I'm not sure it's necessary to get rid of this page and others like it. This page got 1277 pageviews so far this quarter (Aug-Oct), averaging between 400-500/month.

In the short-term, I'd be in favor or changing the scary language on the page and also discussing the broader issues with a few PMs. I think this would be a combination of all product areas.

Is pageviews the right metric? Do we know that folks didn't land on the page because of a search? Do we track the dwell time to know if they actually found something useful on the page?

[jseldess]

Good questions. I'm not sure if it's the right metric. Just grabbed it real quick.

[exalate-issue-sync]

Jesse Seldess (jseldess) commented:
Piyush Singh, Andy Woods, Nick Lamb , do any of you have opinions about this?

[exalate-issue-sync]

Andy Woods (awoods187) commented:
I think we should remove the warning and be specific about what each one does or doesn't do. Some settings, IMO, shouldn’t be documented if we don’t want any user to every know about them and set them.

[exalate-issue-sync]

Stephanie Bodoff (stbof) commented:
Andy Woods The problem is that the table of settings on this page is generated. We can’t exclude some settings (at least we don’t have the mechanism to do that now). We can only remove the page and only document the settings in the pages where we describe when you would use the setting and how to configure the setting. Users would encounter the setting when they read the surrounding content. If a setting was introduced in a release note, the user would have to search for the setting to find the full description of how to use it or the release note could link to the page that describes how to use the setting.

[exalate-issue-sync]

Jesse Seldess (jseldess) commented:

There is actually a way, in the crdb code, to flag a setting for exclusion from the auto-generated doc. In the short-term, given that I know that internal users reference this page and sometimes point external users to the page, I propose we do that following:

Open a docs PR to remove the scary warning.

Audit the settings that get included.

For each setting that should be excluded, file a crdb issue to get that done.

For settings that should stay included, open a crdb PR to improve the descriptions.

Thoughts?

[exalate-issue-sync]

Andy Woods (awoods187) commented:
I like that approach!

[exalate-issue-sync]

Stephanie Bodoff (stbof) commented:
We need to make the process to hide settings we don’t want folks to change documented and widely known. See #12860 (comment) .

The process seems to be described here:

[https://cockroachlabs.slack.com/archives/CV581CE78/p1643324885961719|https://cockroachlabs.slack.com/archives/CV581CE78/p1643324885961719|smart-card]

[exalate-issue-sync]

Stephanie Bodoff (stbof) commented:
See comment here: https://cockroachlabs.atlassian.net/browse/DOC-2634?focusedCommentId=89742

[exalate-issue-sync]

Ian Evans (ianjevans) commented:
In discussing the cluster settings page on Slack, several engineers thought we needed to keep the page. One possibility I floated was that the release notes script could diff the cluster settings page for new/updated/removed settings. That way customers could tell when a cluster setting was added, changed, or removed in both major and patch versions.