Docs: Versioned Documentation

[sos0]

Docs: Versioned Documentation

[wzdxy]

Prohibiting access to old versions of next.js documents will not accelerate my upgrade to the latest version, it will only make me hope for a replacement.
Because even if I upgrade to v14 now, once v15 is released, I won't be able to see the documentation for v14 again.
Difficult to understand behavior.

[delbaoliveira]

Hey @sos0 👋🏼 I maintain the Next.js docs, versioning is something I'd like to have as well.

Historically, I've prioritized writing content because there were so many new breakneck speed App Router features to document. But as APIs in the App Router evolve, we need a way to make it clearer which features are experimental, stable, or not available in x version, etc.

Versioning could solve many of these problems, but I don't have a clear, sustainable long-term implementation yet. Especially when it comes to the maintenance burden / accuracy of older versions - something that's hard to control with open-source docs.

But tldr, it's cooking 😊

[sos0]

Hey @sos0 👋🏼 I maintain the Next.js docs, versioning is something I'd like to have as well.

Historically, I've prioritized writing content because there were so many new breakneck speed App Router features to document. But as APIs in the App Router evolve, we need a way to make it clearer which features are experimental, stable, or not available in x version, etc.

That makes sense, but I'd like additional clarification why versioning would impact notes on experimental/stable/etc. I think once you have documentation versioning, it actually minimizes the need for adding those sort of notes into the document. Personally, development intent and direction is not what I expect to see in documentation, but moreso in a dev blog or forum.

Versioning could solve many of these problems, but I don't have a clear, sustainable long-term implementation yet. Especially when it comes to the maintenance burden / accuracy of older versions - something that's hard to control with open-source docs.

But tldr, it's cooking 😊

Maintenance burden is exactly why the community is here to help with extra eyes and pull requests, which is especially made possible and streamlined in open-source documentation. It may be cooking, but we're the epitome of Too Many Chefs 🧑‍🍳

I do think overall the maintenance is becoming increasingly difficult because Next.js team is prioritizing shipping features within minor versions rather than major. Regardless of difficulty, features and breaking changes are incredibly important to be outlined for developers. I don't know if versioning for public-facing documentation is truly an impossible task since they are compiled and versioned already on Github.

I would appreciate if this issue could be remained open unless the team is already decided on not working on this.

[github-actions]

This closed issue has been automatically locked because it had no new activity for 2 weeks. If you are running into a similar issue, please create a new issue with the steps to reproduce. Thank you.