Docs: Diátaxis refactor - iteration 0 high-level tracking

[benjaoming]

In order to be able to work on subsequent iterations, we need to firstly add the following features to our documentation:

• Existing doc PRs are merged or marked as blocked:

  • Docs: cancel PR builds if there is no documentation changes #9734
  • Add an initial policy for delisting unmaintained projects #9731
  • Search: API V3 #9625
  • Docs: policy for supported tools and dependencies #7859 blocked

• In the proposed structure, Explanation mixes Business and Community features. This will require a simple DRY way of repeating the same “This feature is only available on Read the Docs for Business” kind of box. We could use a Sphinx replacement directive for this. Docs: Adding a pattern for reusing "Only on Read the Docs for Business" admonition (Diátaxis refactor) #9754

• Open a long-lived diataxis/main feature branch, which we may merge into main at the end of each iteration (or not)

• Retarget existing PRs to diataxis/main

• Establishing a basic layout for Explanation, How-To and Reference:

  • Tutorials replaces “First steps”
  • Explanation is added before “Features” & “Advanced Features”
  • How-to stays
  • Reference is added, moving the simplest existing references there immediately so it’s not empty
  • Read the Docs for Business and About Read the Docs simply stay put (Read the Docs for Business is dissolved in Iteration 1 and About Read the Docs is dissolved in Iteration 2)
  • Docs: 4 diátaxis categories at the top of the navigation sidebar (Diátaxis iteration 0) #9758

[benjaoming]

@ericholscher I've added the last item just now

Open a long-lived diataxis feature branch, which we may merge into main at the end of each iteration (or not)

The idea was that we should have this branch up-front and add a public&hidden version for the branch.

[ericholscher]

Yep, agreed 👍

[benjaoming]

Looking at the last item now in the list (which changes the sidebar navigation), I think this will be a good "first step" to launch that branch and then rehearse how we will evaluate if it's going into main or not!

[benjaoming]

This is all done now and ready for Iteration 1 #9746 🎉