Docs: distinguish between frequently, commonly, and rarely used options

[rarkins]

Describe the proposed change(s).

Today our config options list is huge. More features is good, but for someone starting out it's intimidating to browse through.

Ideally we need a way to highlight to people both:

• Commonly used settings they may be interested in when they get started, and
• Features which are rarely used, so they can probably skip over reading unless they have a real need

If we just wanted to highlight commonly used settings, that can or should also be done using getting started guides/tutorials. But even if so it would still be good to mark features as proposed to make them more quick to skim through.

We could also consider breaking complex options like packageRules and hostRules into their own page.

[HonkingGoose]

I like your ideas! I agree that the config options docs are overwhelming, it's a big list of options with no "how often should I use this"-ranking.

We should definitely highlight common/rarely used features in some way.

Breaking out complex options into own page

If we just wanted to highlight commonly used settings, that can or should also be done using getting started guides/tutorials. But even if so it would still be good to mark features as proposed to make them more quick to skim through.

I already created some key concepts pages for things like our Dependency Dashboard, Pull Requests and Automerge. We could break out packageRules and hostRules into their own key concepts pages?

We already have an issue tracking creating new "key concepts pages", see:

• Key concepts sidebar for dashboard, scheduling, grouping, automerge #11237

We have a lot of custom code for generating the docs pages, so we'll need to change the docs generating code to account for the break out of those config options.

Highlight common/rare stuff

Material for MkDocs can only tag pages

I first thought about using the tags feature in Material for MkDocs, but that's intended to tag a page not sections of that page, quote from the tags docs: ¹

Material for MkDocs adds first-class support for categorizing pages with tags, which adds the possibility to group related pages and make them discoverable via search and a dedicated tags index. If your documentation is large, tags can help to discover relevant information faster.

Put usage frequency in code somehow

We already have a experimental Boolean in our code, based on that Boolean we add a experimental feature admonition in our docs. We could use something similar to label the usage frequency of config options.

renovate/lib/config/options/index.ts

Lines 125 to 135 in 57e1e64

	{
	name: 'configMigration',
	description: 'Enable this to get config migration PRs when needed.',
	stage: 'repository',
	type: 'boolean',
	default: false,
	experimental: true,
	experimentalDescription:
	'Config migration PRs are still being improved, in particular to reduce the amount of reordering and whitespace changes.',
	experimentalIssues: [16359],
	},

Array

const usageFrequencyValidValues = ["never", "sometimes", "often", "all the time"] // Only allow values from this array, validate this in code somehow

// In code:

{
  name: 'configMigration',
  description: 'Enable this to get config migration PRs when needed.',
  stage: 'repository',
  type: 'boolean',
  default: false,
  experimental: true,
  experimentalDescription:
    'Config migration PRs are still being improved, in particular to reduce the amount of reordering and whitespace changes.',
  experimentalIssues: [16359],
  usageFrequency: 'often',
},

Create custom type/object?

There's probably a better way than the simple array above, like creating a custom type or special object? 😉

Mockup of end result in docs

In any case, the end result would be that the usage frequency is added to the table in the docs:

configMigration

Enable this to get config migration PRs when needed.

Name	Value
type	boolean
default	false
cli	--config-migration
env	RENOVATE_CONFIG_MIGRATION
usage frequency	often

Footnotes

1. https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/ ↩