Docs: Navigation reorder (Diátaxis) #10026

benjaoming · 2023-02-14T21:31:09Z

This reorders the navigation, anticipating new top-levels to be created in the next iteration.

📚 Documentation previews 📚

User's documentation (docs): https://docs--10026.org.readthedocs.build/en/10026/

Developer's documentation (dev): https://dev--10026.org.readthedocs.build/en/10026/

benjaoming · 2023-02-14T21:49:26Z

Maybe @humitos has ideas for Tutorial/How-to/Explanation/Reference emojis :)

ericholscher

This is a reasonable refactor, but still feels like there's some polish needed. This is a good middle step tho.

docs/user/index.rst

ericholscher · 2023-02-14T23:11:00Z

@benjaoming I'm gonna do a commit on top of this to address a couple ideas.

ericholscher · 2023-02-15T00:54:31Z

Alright, I did a bunch of refactoring. I think the real takeaway here is that we don't have much in the way of explanation content written yet. I moved a lot of content out of that section because it didn't really belong there as currently written.

I do worry a bit that we're back in the place of having done a bunch of content improvements here, but have made the docs a bit less usable for normal users by hiding a bunch of content below the top-level TOC. There is always going to be a trade-off though between an overwhelming TOC, and better structure and nesting. I think most people will be finding content via Google though, so I'm not too worried in general, as long as it's possible to find it via navigation.

I think some of the future index page updates will help there, and building out a few other small indexes for each of the sections.

benjaoming · 2023-02-15T11:50:00Z

Alright, I did a bunch of refactoring. I think the real takeaway here is that we don't have much in the way of explanation content written yet. I moved a lot of content out of that section because it didn't really belong there as currently written.

That makes the navigation look better and less overwhelming - which was intended as next steps :)

And it also fills up the Feature Reference to look more complete, which I understand is very important.

But it also moves 10 articles where the content was written as explanation. So that'll leave some refactoring debt.

Examples:

this is not a how-to, it's explanation: https://docs--10026.org.readthedocs.build/en/10026/automatic-redirects.html - I think it should be moved back, but we can invent a format that fits well to cases like this: "Best practices for " or "Steps to make a documentation more "
This was an explanation: https://docs--10026.org.readthedocs.build/en/10026/canonical-urls.html - the feature reference should also exist, but again we'd need to figure out a good "template" for how we want to represent the a) explanation of a concept and b) the feature.

benjaoming · 2023-02-15T11:15:24Z

docs/user/connected-accounts.rst

+How to connect your Git repository
+==================================


This was intended as an explanation since there isn't anything actionable. I can guess at several reasons that a user should read the article, and since some of them are also how-to oriented, I don't see anything bad with the refactor.

We can call it a how-to, that can work as well 👍

docs/user/index.rst

benjaoming · 2023-02-15T11:53:15Z

docs/user/integrations.rst

+Continuous Documentation Deployment
+===================================


I'm a very big fan of this!

Even shortening it to "Continuous Documentation" can be an interesting way of talking about the workflow and the technical platform at the same time.

benjaoming · 2023-02-15T11:55:57Z

docs/conf.py

@@ -61,6 +61,7 @@
 release = version
 exclude_patterns = ["_build", "shared", "_includes"]
 default_role = "obj"
+intersphinx_cache_limit = 14  # cache for 2 weeks


benjaoming · 2023-02-15T11:57:31Z

docs/user/about/index.rst

@@ -68,7 +53,23 @@ we've brought most of the most important ones below.
 ⏩ :doc:`/support`
   Read this before asking for help: How to get support and where.

+⏩ :doc:`/glossary`
+   A useful index of terms used in our docs


This seems like a wrong location for our Glossary?

Is it because you think the discoverability of the page itself isn't valuable? I tend to agree with that. So kind of 🧹 'ing into this corner seems fine until it has so many terms that it's a real resource.

I think we need some other reference index to hide this stuff under, rather than in the top-level nav, is the real answer.

benjaoming · 2023-02-15T11:58:05Z

docs/user/commercial/sharing.rst

-Sharing
-=======
+Private Documentation Sharing
+=============================


benjaoming · 2023-02-15T11:58:35Z

docs/user/guides/authors.rst

   Migrate from rST to MyST <migrate-rest-myst>
   enable-offline-formats
   Using search analytics <search-analytics>
+   /automatic-redirects
+   /science


hahaha, this page will keep moving around because it's such a hack.

BUT it's noted for later 👍

Yea, I mostly just hid it away since it doesn't need to be in the top nav. I think it could live under a top-level Tutorials page like Specific use cases or something?

benjaoming · 2023-02-15T11:59:47Z

docs/user/index.rst

@@ -198,7 +183,7 @@ out of your documentation and Read the Docs.

 * **Advanced project configuration**:
  :doc:`subprojects` |
-  :doc:`Single version docs <single_version>` |
+  :doc:`Single version docs <single-version>` |


redirect needed?

Already created.

benjaoming · 2023-02-15T12:04:04Z

Great work! Many great changes! Seems good to go ✔️

I went over all the changes here, noted a few things that might need follow-up and more generally the 10 moved explanation articles.

ericholscher · 2023-02-15T15:00:20Z

this is not a how-to, it's explanation: https://docs--10026.org.readthedocs.build/en/10026/automatic-redirects.html - I think it should be moved back, but we can invent a format that fits well to cases like this: "Best practices for " or "Steps to make a documentation more "

I would argue it's much closer to a How To than an explanation, given that the primary content is a set of Do's and Dont's? That feels less like explanation and more like "A list of things to do" to me.

This was an explanation: https://docs--10026.org.readthedocs.build/en/10026/canonical-urls.html - the feature reference should also exist, but again we'd need to figure out a good "template" for how we want to represent the a) explanation of a concept and b) the feature.

I'm also not sure this is useful enough to be a top-level explanation? Perhaps we need more nesting for "niche" explanations like this. But I don't see this content as something a normal user needs to care about really at all?

In particular the entire https://docs--10026.org.readthedocs.build/en/10026/canonical-urls.html#how-read-the-docs-generates-canonical-urls section seems like feature content to me?

benjaoming · 2023-02-15T15:13:20Z

I would argue it's much closer to a How To than an explanation, given that the primary content is a set of Do's and Dont's ?

I imagined a refactor where the objective is to avoid mixing how-to and explanation by means of:

Creating a simple and actionable list of do's and don'ts as you mentioned. But the "executive summary"
Keeping the bulk of the current article as the longer explanation, perhaps removing the simplest actionable stuff and referring to the "How-to: Best practices for SEO"-ish article

benjaoming · 2023-02-15T15:15:06Z

I'm also not sure this is useful enough to be a top-level explanation?

Definitely agreeing that it's not a very important article to figure as a top-level. I think you did a wonderful work on getting the current navigation to be very beautiful and easy to read.

I had an intention to be more pragmatic to accept more overwhelming amounts of items in Explanation because of the next steps to add new sub-levels in Explanation and How-to.

ericholscher · 2023-02-15T15:22:21Z

I didn't really make it less overwhelming as a goal, I just removed the things that didn't make sense at the top-level, because I think that's the best trade-off. We want the top-level nav to have the high-value things, and other stuff to be findable with indexes and search.

humitos · 2023-02-16T07:09:56Z

Maybe @humitos has ideas for Tutorial/How-to/Explanation/Reference emojis :)

I'd put the emojis at the beginning of the sentence so they are all aligned:

Also, I would not use emojis on the inner links because it make them more prominent and differentiate over the others. In particular, "Developer Documentation", is the least important one but it's the most prominent in that section now because of the emoji.

benjaoming added 5 commits February 14, 2023 22:02

Put the toctrees at the top of index.rst content

69a3403

Re-order explanation

0b03097

Move how-to guides before explanation

3d35525

Emojis in navigation

e2fac21

re-order reference items

d3f67e3

benjaoming added Improvement Minor improvement to code Needed: documentation Documentation is required labels Feb 14, 2023

benjaoming requested a review from ericholscher February 14, 2023 21:31

benjaoming requested review from a team as code owners February 14, 2023 21:31

benjaoming requested a review from agjohnson February 14, 2023 21:31

auto-assign bot assigned benjaoming Feb 14, 2023

benjaoming changed the base branch from main to diataxis/main February 14, 2023 21:31

benjaoming removed the request for review from agjohnson February 14, 2023 21:31

ericholscher reviewed Feb 14, 2023

View reviewed changes

ericholscher added 3 commits February 14, 2023 15:48

Lots of TOC refactoring

2191ddb

A bit more futzing

6e40547

Remove underscores from files, and do a bit more cleanup

877f2e0

ericholscher added 2 commits February 14, 2023 16:55

Fix links

e041d25

Single TOC for all

80c9f2e

benjaoming commented Feb 15, 2023

View reviewed changes

docs/user/commercial/sharing.rst

Sharing

=======

Private Documentation Sharing

=============================

Copy link

Contributor Author

benjaoming Feb 15, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💯

benjaoming commented Feb 15, 2023

View reviewed changes

benjaoming merged commit 602f5de into readthedocs:diataxis/main Feb 15, 2023

benjaoming deleted the diataxis/navigation-reorder branch February 15, 2023 12:04

benjaoming mentioned this pull request Feb 15, 2023

Docs: Diátaxis refactor - iteration 2 high-level tracking #9747

Closed

31 tasks

benjaoming mentioned this pull request Feb 16, 2023

Docs: emojis in TOC captions, FontAwesome on external links in TOC (Diátaxis) #10039

Merged

		How to connect your Git repository
		==================================

		Continuous Documentation Deployment
		===================================

Uh oh!

Docs: Navigation reorder (Diátaxis) #10026

Docs: Navigation reorder (Diátaxis) #10026

Uh oh!

Conversation

benjaoming commented Feb 14, 2023 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

benjaoming commented Feb 14, 2023

Uh oh!

ericholscher left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ericholscher commented Feb 14, 2023

Uh oh!

ericholscher commented Feb 15, 2023

Uh oh!

benjaoming commented Feb 15, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ericholscher Feb 15, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

benjaoming commented Feb 15, 2023

Uh oh!

ericholscher commented Feb 15, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

benjaoming commented Feb 15, 2023

Uh oh!

benjaoming commented Feb 15, 2023

Uh oh!

ericholscher commented Feb 15, 2023

Uh oh!

humitos commented Feb 16, 2023

Uh oh!

Uh oh!

benjaoming commented Feb 14, 2023 •

edited by github-actions bot

Loading

ericholscher Feb 15, 2023 •

edited

Loading

ericholscher commented Feb 15, 2023 •

edited

Loading