Have a "Who can use this feature?" call out in our docs

[HonkingGoose]

Tell us more.

Intro

The GitHub docs, configuring Dependabot version updates have a callout/admonition that explains who can use a feature. For example:

Who can use this feature?

👤 People with write permissions to a repository can enable or disable Dependabot version updates for the repository.

I like this idea very much, and want to do something similar for our docs.

Technical details

I'm thinking of creating a custom admonition, like the GitHub one, and using it:

• At the top of stand-alone explanation pages
• In relevant paragraphs
• Maybe for each configuration option, but it's probably better to add a new field "who can use this feature" to the details table for each config option

Custom admonitions documentation

• Material for MkDocs, create a custom admonition.

Tell me what you think!

What do you maintainers think of this idea? 😄

[rarkins]

Can you give an example?

[HonkingGoose]

This is good, but I'm not sure we should specify read privileges as it might require a lot.

Most of Renovate's features are accessible to read only users, as they can always see the Dependency Dashboard issue, and the PRs that Renovate creates.

So it sounds logical to focus on the things you need elevated permissions for.

Do you want me to make the custom admonition for us then?

[HonkingGoose]

@rarkins So are you happy for me to start working on these todos? I did not get a clear go/no go from you yet. 😉

• Creating a new admonition style for Who can use this feature
• Using the admonition for the narrow number of capabilities which need extra privileges (adding labels, checking boxes in PRs, etc)

[rarkins]

Can you first work out how many such admonitions would be necessary? I'm undecided if this can be done with regular Notes or if we want a new table row

[HonkingGoose]

I'm not sure how many admonitions we need, I would need to go through each page in the docs separately to see what we need. I have a feeling I would want to use the admonition on nearly every page.

I think there's a bigger problem than just creating/using the admonition. I'll explain below.

Who is the intended reader for a page/section?

The main thing is that most pages do not explain which is the intended reader for that page. Is the page for:

• Beginners?
• Intermediates?
• Advanced users?

Some pages even mix those kinds of information, without marking which sections are for which audience.

Docs "difficulty" all over the place

The current docs structure leads to a bad difficulty curve. It's very easy to go from a easy page, to deep in the woods technical mumbo jumbo page the next.

Try clicking on the sidebar links in sequence, and note how the difficulty jumps around. Here's the first few pages in sequence:

• Homepage, easy
• Reading list, easy to hard. But users can choose their difficulty 🙃
• Use cases, medium/hard. I find this goes in-depth way too soon. It should explain "What can Renovate do for me" first, and only then, for those that want it, explain the technical details.
• Running Renovate, hard. Gives a skip link for the Mend Renovate App users, or those who have somebody else hosting Renovate for them.
• Self-hosting examples, medium. Users can select which situation applies to them.
• Installing and onboarding, medium. I feel we should split this into separate pages:
  • Installing hosted app
  • Installing Renovate when self-hosting
  • Generic page about repository onboarding
  • Generic page about reconfiguration
• Private packages, hard. This is really into the weeds about authentication, credentials, encryption.
• Observability, hard. This page feels out of place in a "Getting started" section. This feels more of a "deep dive" thing to me.

Admonitions short-term workaround, real fix is better docs structure

I like the "Who can use this feature" admonition idea, because it helps, in the short term, to explain who is the intended audience for a feature/page/concept. I would want to use it on nearly every page, because:

• It forces us as writers, and maintainers, to be clear about the intended audience of the content.
• It makes us think about splitting difficult pages into separate pages (or sections) for each kind of reader.
• It's the same format each time, so readers will get familiar with this styling and know what to expect from it.
• Readers can self-select if they need the info on the page.
• We can link to different sections on the page for different type of readers.

But the real fix is to re-order and rewrite pages. With the end goal being a smooth ramp up in difficulty, and a clear up-front explanation of each page, and who can use the information on the page/section.

[rarkins]

Some pages even mix those kinds of information, without marking which sections are for which audience.

This is necessary and expected for reference pages, such as config options. I agree with you that other pages which are intended as "guides" should ideally have a target audience in mind