search

cockroachdb / docs

CockroachDB user documentation
https://cockroachlabs.com/docs
Creative Commons Attribution 4.0 International
188 stars 456 forks source link

cluster settings - general page utility #11981

Open ghost opened 3 years ago

ghost commented 3 years ago

Stephanie Bodoff commented:

Regarding the page itself:

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

jseldess commented 3 years ago

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.

ghost commented 3 years ago

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 commented 3 years ago

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

exalate-issue-sync[bot] commented 2 years ago

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

exalate-issue-sync[bot] commented 2 years ago

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[bot] commented 2 years ago

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[bot] commented 2 years ago

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[bot] commented 2 years ago

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

exalate-issue-sync[bot] commented 2 years ago

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 https://github.com/cockroachdb/docs/pull/12860#discussion_r794052547 .

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[bot] commented 2 years ago

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

exalate-issue-sync[bot] commented 2 years ago

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.

exalate-issue-sync[bot] commented 2 years ago

Stephanie Bodoff (stbof) commented: A similar problem afflicts the built-in SQL functions: https://www.cockroachlabs.com/docs/v22.1/functions-and-operators.html#built-in-functions . The descriptions leave a lot to be desired.