[Proposal] Complexity management in valkey-doc publishing

[stockholmux]

I was asked the question "where is the getting started for Valkey?" and, indeed, it is here in valkey-doc, but it's yet to move through all the phases of publishing.

Checking, updating, and publishing this single page is trivial (20-30 minutes on-task + PR approvals), but I started to look at how many links it contained, and then how many links those pages contained (and so on). A bit of a problem emerged: this single page is connected to almost every other page.

I mapped it out:

I stopped at about 40 documents, but I'm confident that it transitively connects to every other document in the docs.

If I were to publish this single page, I'd need to publish everything at once to prevent broken links. This means Valkey is going to be very far away from being able to publish even simple pages.

I see a few ways to proceed:

1. Do nothing until everything can be published. I don't like this as there are people who want to use Valkey right now and won't have a good way to read the documentation.
2. Publish and not worry about broken links. I don't really like this. The 404 links are not good for site health or ranking and it's a poor user experience.
3. Work our way from less linked pages to more linked pages Find a documentation pages with few links and publish those first, ending with the most linked pages. This would work but in practical purposes, we'd end up with the more obscure and specific pages being published first, with no way to prioritize gradual publishing.
4. Selectively pare down links to make pages more easily publishable: Find the most impactful pages and publish those, removing links as required to publish more quickly. Any removed links would be added as an issue so they can be added back later when the linked pages are also published.

My preference is option 4. This will cause a little bit of PR/issue churn but it will keep track of the links while still unblocking publishing. Option 3 could be viable but there will be a period where our documentation will be not very useful. Option 1 and 2 feel like big anti-pattern and probably should be avoided.

I'd like to get some others to chime as dissenting or agreed before proceeding because.

[zuiderkwast]

I've been doing many passes on the docs and IMO it's almost ready to publish all under topics.
Before we publish it though, I'd like to

• Make sure we don't want to rename any of the pages again (since we don't have proper redirects).
• Check for broken links and fix them.
• Merge Add TOC page with links to the documentation pages #75.

[zuiderkwast]

And

• get rid of the Hugo junk {{< .. >}}

[stockholmux]

@zuiderkwast So, you're advocating for option 1?