Docs: Split Custom Domains as Explanation and How-to Guide (Diátaxis)

[benjaoming]

• Splits Custom domains into 2 articles:
  • Explanation / Custom Domains
  • How-To Guides / How To Manage Custom Domains

Intentional scope creep, refs: https://github.com/readthedocs/readthedocs.org/pull/9676/files#r1035201538

• Split "Canonical URLs"
  • Explanation / Canonical URLs: Effectively archiving old versions
  • How-to / How to use Canonical URLs

Fixes #8469
Refs #9746

---

📚 Documentation previews 📚

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

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

[benjaoming]

At first, I thought that a good text about custom domains would end up missing in the features reference - but it turns out, the subject is already covered here: https://docs.readthedocs.io/en/stable/hosting.html

[benjaoming]

Takeaways from discussion about how the first easy Diátaxis refactors should take place and be reviewed focused on this PR, so here are the comments:

• This PR is too "sloppy", so it leaves behind more questions and doesn't allow an easy decision
• We can try to improve title and intro to match the How-To part more
• Remaining reference is still important for the Features Reference, so we should try to keep that in its current location
• Finally, we can observe if this was an "easy change" worth repeating or we should postpone this kind of change for later. Possibly, we might even entirely scrap this change if it cannot be done Easily (TM).

[benjaoming]

Another take-away: We don't want to clog up the reviewing process with too many PRs. So I'll keep an absolute maximum of 10 PRs and me and @humitos will evaluate - maybe by end of Thursday.

[agjohnson]

From our meeting;

We talked a bit about this page specifically -- this is a good example page because it does have more of the content that we'd like to have for each feature. So, I'll home discussion notes here. This might be a great feature to iron out some of our patterns on, given it is more complex. But some of this is applicable to all feature pages.

We noted:

• Our end goal is probably more structure to our feature pages, especially for more complex examples like this. Pages like /custom-domains can't easily be repurposed to just one type of content (how-to), as there is reference content on this page, and there should be (more) explanation content around the top-level topic "What are custom domains?"
• It seems we're describing the need to split up pages into more granular content pages. This is especially true if we consider all of the content that is missing or needs rewritten, and content we want to have in the future.
• Most of what we discussed was restructuring. It makes sense for us to have a high tolerance on content issues while we're working on structure.
• Some of the content we're describing does not exist
• We can gain a lot of value out of restructuring documents and navigation structure still, and this is probably still the easiest change to start with.

So, perhaps we still need to define our end goal around structure. This is something we can discuss, but as a starting point:

• Each feature needs explanation content at a top-level. "What is $feature?". This should be technical description of the feature, where the communication style on our website is marketing flavored.
• Most features need how to pages for "How to managed $feature"
• Some features will have reference content for technical details
• Most features will have how to content for "Troubleshooting $feature"

It's not clear if we're at the point that we're talking about splitting up into pages /features/custom-domains/managing-custom-domains and /features/custom-domains/troubleshooting, but this does seem like it could be a direction to go that would provide an easy framework to follow for each feature page.

[benjaoming]

I think that we need a separate discussion dedicated to proposals for an over-all navigation structure / topic template.

[benjaoming]

But I like where the idea is heading!

[agjohnson]

I think that we need a separate discussion dedicated to proposals for an over-all navigation structure / topic template.

Yeah, and there are probably two conversations there too: what navigation structure do we need for features immediately, and what navigation structure changes are there overall.

We can probably discuss the two in isolation, if it helps to be explicit with our initial plan. However, I think what we described so far is that existing navigation structure shouldn't change much yet. Instead, we're talking about adding new pages, and mostly need to find homes for content that we're moving.

Overall, there are conversations around where we move feature content for RTD for business, guide content that borders on explanation content or general feature content, etc.

[agjohnson]

I think we're to the point where more semantic structure would help organization of all of these concepts. /guides/ path has always been a dumping ground for misfit pages that don't fit elsewhere and so it's really not clear what purpose the path /guides/ serves anymore.

I think it's best to create new structure that has more semantic meaning for feature sub pages, like:

• /features/managing/custom-domains
• /features/troubleshooting/custom-domains
• /features/custom-domains/managing
• Or similar, just something more meaningful

[humitos]

I think this is fine. It's definitely better than what it was before 💯

It follows some of the topics that we discuss in our meeting and it splits the content in the way we talked:

• "feature" page with an introduction to the topic
• "how to" document that explains how to use the feature itself

It does not split its content into an extra "troubleshooting" page --for now, it seems this content is still under the "how to". Do you think we should do this change on this PR as well? I'd like to have all the changes we would like to do on these pages in one PR, and use it as example for the others. I'm fine if we are skipping this chunk of work on all these PRs for now, tho.

After reading all the good feedback related to English in particular that @agjohnson provided to this PR, I'm not sure I'm the best fit to review all the other ones.

[ericholscher]

Diagram is great, with some nitpicks about the exact language and process.

[benjaoming]

I don't like the unfocused scope of "How To Manage Custom Domains" but I think we can live with this and instead put a note for Iteration 4. I think it'll be easier to make a decision about these "bundled" how-tos once we see them grouped together with all the other how-tos.

Thoughts?

[ericholscher]

I think we can get this merged once my small nitpicks are addressed and we removed the mermaid stuff 👍

This has already taken too much time, so I feel like more investment here is firmly in diminishing returns. We can come back and address any issues once users are using it.

[benjaoming]

Our CSP works well 👍 The SVG generated on mermaid.live has fontawesome included from CDN and it doesn't work.

<style>@import url("https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.2.1/css/all.min.css");'</style>

Will create a PNG. Also Mermaid docs say this:

Mermaid is now only compatible with Font Awesome versions 4 and 5. Check that you are using the correct version of Font Awesome.

And then mermaid.live embeds font-awesome 6 🙃

[benjaoming]

Mermaid Diagram finally works. A bit more cumbersome, but end result looks good to me.