Reorganize the project concept documentation

[zanieb]

• Adds a collapsible section for the project concept
• Splits the project concept document into several child documents.
• Moves the workspace and dependencies documents to under the project section
• Adds a mkdocs plugin for redirects, so links to the moved documents still work

I attempted to make the minimum required changes to the contents of the documents here. There is a lot of room for improvement on the content of each new child document. For review purposes, I want to do that work separately. I'd prefer if the review focused on this structure and idea rather than the content of the files.

I expect to do this to other documentation pages that would otherwise be very nested.

The project concept landing page and nav (collapsed by default) looks like this now:

[dhruvmanila]

I think splitting larger pages into does make sense. We should enable navigation.path (navigation path breadcrumbs) so that it's easy to understand where the user is currently at. It might be problematic because of the "Introduction" page that exists currently but that can possibly be solved.

I'm still a big fan of having a third dimension to navigation aka tabs where the top level sections go but that's an unrelated discussion.

[dhruvmanila]

One thing I noticed is that the footer seems to be a bit annoying when clicking on the "Projects" section because it occupies the entire screen width. I don't know if it's possible but limiting that only to the content region (and not the navigation and table of content) would be a good UX improvement IMO.

[zanieb]

I'm still a big fan of having a third dimension to navigation aka tabs where the top level sections go but that's an unrelated discussion.

Agree, it just makes it a lot harder to incrementally add more sections because it's a weird experience to switch to tabs without creating and populating a lot of child pages.

One thing I noticed is that the footer seems to be a bit annoying when clicking on the "Projects" section because it occupies the entire screen width. I don't know if it's possible but limiting that only to the content region (and not the navigation and table of content) would be a good UX improvement IMO.

I feel the same. In my larger reorg, I actually implemented this in an attempt to show more of the nav

However, this requires JS to dynamically move the element by editing the DOM (you can't style it up into the content).

I think we either need to fork our own theme and change it there, or... idk.

Edit: I had another idea that should solve this in the meantime — #9153

[zanieb]

We should enable navigation.path (navigation path breadcrumbs) so that it's easy to understand where the user is currently at. It might be problematic because of the "Introduction" page that exists currently but that can possibly be solved.

This seems to have no effect locally for me, which is surprising. I agree it'd be nice to have — I think I tried turning it on previously but was annoyed by the "Introduction" page as you mentioned.

[dhruvmanila]

This seems to have no effect locally for me, which is surprising.

Oh interesting. The following diff seems to be showing the breadcrumbs for me locally:

diff --git a/mkdocs.template.yml b/mkdocs.template.yml
index b68729f48..d8c88a525 100644
--- a/mkdocs.template.yml
+++ b/mkdocs.template.yml
@@ -4,7 +4,7 @@ theme:
   logo: assets/logo-letter.svg
   favicon: assets/favicon.ico
   features:
-    - navigation.collapsible
+    - navigation.path
     - navigation.instant
     - navigation.instant.prefetch
     - navigation.instant.progress

But, it does include the "Introduction":

In my larger reorg, I actually implemented this in an attempt to show more of the nav

This looks good. Is this a mockup or is the "reorg" a code change? I'm curious to look at the diff if it's available.