docs: create dependency dashboard showcase page

[HonkingGoose]

Changes:

• Create dependency Dashboard showcase page

Context:

Fixes #11178.

Todo's:

• Get feedback on draft PR
• Resolve all TODO: in the current PR
• Discuss whether we want to add screenshots
• Add the new page to correct place in sidebar in the Renovate Docs repository, edit file: https://github.com/renovatebot/renovatebot.github.io/blob/build/mkdocs.yml

Documentation (please check one with an [x])

• I have updated the documentation, or
• No documentation update is required

How I've tested my work (please tick one)

I have verified these changes via:

• Code inspection only, or
• Newly added/modified unit tests, or
• No unit tests but ran on a real repository, or
• Both unit tests + ran on a real repository

[HonkingGoose]

Do we want to have screenshots of the dashboard?

Benefits:

• Pictures help to liven up the page so it's not just a wall of text
• Pictures are a good way to show why you want to have the dashboard
• Helps market the feature to new prospecting users who are reading the docs to find out if Renovate is a good fit for them

Drawbacks:

• Pictures will need to be updated to match current design (example when we implement issue #10924)
• Increases size of repository a bit
• Requires maintainer time to update pictures

[HonkingGoose]

Commenting the current TODO comments.

[HonkingGoose]

I'll stop pushing new stuff into this branch.

I have a feeling I'll need to change filename/directory structure because of #11202 anyways...

Can you let me know how you want me to proceed @rarkins?
I'll have time to work on this tomorrow.

[HonkingGoose]

@rarkins What do you want me to do with the filename/directory structure of this PR?

I think the new dependency-dashboard.md file could go in the sidebar under the getting-started fold-out. Or we could have the dependency-dashboard.md page as a separate entry.

We could end up with this:

• getting-started
  • dependency-dashboard.md
  • installing-onboarding.md
  • private-packages.md
  • running.md
  • use-cases.md

Or we could put dependency-dashboard.md in the docs/usage folder on its own.

[rarkins]

@HonkingGoose I don't think we should overload Getting Started too much. I think we have some core concepts like dashboard, scheduling, grouping and automerge which could together be in a common folder, such as "Key Concepts"?

[HonkingGoose]

I really, really like your idea to have a "Key concepts" folder! It's really clean how scheduling, grouping, automerge, and dependency dashboard all can go under that category! This also makes it easy to see how those features interact and how to cobble things together for best effect.

So the new user of Renovate can read the getting started docs to get a basic overview, and then they can deep-dive into topics they find valuable via the key concepts folder/sidebar.

---

By the way, I find it really hard to work on the docs when making big sweeping changes like this, as I do not have a preview of my changes in a visual way.

How do you and @viceice work on the docs right now? Is it "pray we've done everything right, and fix the broken stuff as we stumble upon it", or do you have a way to build the docs as a "preview"?

[rarkins]

Unfortunately I don't have any great way to do that.

Something we definitely want to do differently is move all building of this repo's modules docs here, instead of in renovatebot.github.io. Then the latter repo is more just pulling together the content instead of generating it.

The next step might be to document in the other repo how to replace the current submodules reference with a branch you're working on. After that you could verify the docs locally by running the build command and then cd site && npx http-server.

[HonkingGoose]

Unfortunately I don't have any great way to do that.

Oh okay... Figured it was worth asking, maybe I missed some way to get a preview with the current setup...

Something we definitely want to do differently is move all building of this repo's modules docs here, instead of in renovatebot.github.io. Then the latter repo is more just pulling together the content instead of generating it.

That would at least mean that all the docs stuff is in one place? Right now we generate a bunch of docs based on the .ts files, so I'm not seeing any of that while I'm working on the docs.

The next step might be to document in the other repo how to replace the current submodules reference with a branch you're working on. After that you could verify the docs locally by running the build command and then cd site && npx http-server.

That sounds really clunky, but I'll take it for now, because its still better than no preview method at all. 😄
I've never even used Git Submodules, so the explanation should be very beginner friendly! 😄

I think the Docusaurus 2.0 migration has stalled, or maybe the priorities are elsewhere for now? I haven't seen any work on that in a while now.

---

@rarkins Could you maybe comment on the PR comments how you want me to resolve those? I don't know enough yet to proceed with the document. I think you're waiting on me to release the Dependency Dashboard page for your v26 release?

[rarkins]

Oh okay... Figured it was worth asking, maybe I missed some way to get a preview with the current setup...

We mostly haven't made big changes to docs for a while.

That would at least mean that all the docs stuff is in one place? Right now we generate a bunch of docs based on the .ts files, so I'm not seeing any of that while I'm working on the docs.

Exactly. I would like it that you/we can see how they are generated into .md files within this repo. The reason for not building the whole docs site in this repo is because one day I want it to pull in markdown (including autogenerated) from other things like our Docker image builds, etc.

That sounds really clunky, but I'll take it for now, because its still better than no preview method at all. 😄
I've never even used Git Submodules, so the explanation should be very beginner friendly! 😄

I'm quite a n00b with submodules too. I'm optimistic that the process will be simple though, once we work out what it is. We might even be able to script it so that you can provide a PR number and it will do the rest.

I think the Docusaurus 2.0 migration has stalled, or maybe the priorities are elsewhere for now? I haven't seen any work on that in a while now.

I'd love to see it but I don't really have the skills personally.

@rarkins Could you maybe comment on the PR comments how you want me to resolve those? I don't know enough yet to proceed with the document. I think you're waiting on me to release the Dependency Dashboard page for your v26 release?

Do you mean in this PR?

[HonkingGoose]

@rarkins Could you maybe comment on the PR comments how you want me to resolve those? I don't know enough yet to proceed with the document. I think you're waiting on me to release the Dependency Dashboard page for your v26 release?

Do you mean in this PR?

Yup! 😉

[HonkingGoose]

I'll just post this again, as it will get missed behind the wall of text we have now... 😉

Do we want to have screenshots of the dashboard?

Benefits:

• Pictures help to liven up the page so it's not just a wall of text
• Pictures are a good way to show why you want to have the dashboard
• Helps market the feature to new prospecting users who are reading the docs to find out if Renovate is a good fit for them

Drawbacks:

• Pictures will need to be updated to match current design (example when we implement issue #10924)
• Increases size of repository a bit
• Requires maintainer time to update pictures

[rarkins]

Screenshots would be great, but done is sometimes better than perfect :)

As in, we could defer them to a future PR instead of holding this up

[HonkingGoose]

Screenshots would be great, but done is sometimes better than perfect :)

As in, we could defer them to a future PR instead of holding this up

Let's go with "defer to future PR" then and get this important work merged! 😄

I'll make a new issue to track this proposal. 😄

[renovate-release]

🎉 This PR is included in version 25.75.0 🎉

The release is available on:

• GitHub release
• 25.75.0

Your semantic-release bot 📦🚀