Docs: Move and update FAQ (Diátaxis)

[benjaoming]

Refs: #9746

The FAQ doesn't fit that well in Diátaxis in the sense that it's a very unstructured way of delivering content. I also invites "dumping" of documentation, which is a bit of an anti-pattern. So I'll consider it "deprecated" but that we shouldn't delete it before the decision is very easy to take.

Placement as How-To: I think it's very much a how-to, since an FAQ requires the user to know the problem they want to solve and need an instruction on how to solve it. Most likely, it's because they follow an internal link.

I'll clean it up with the following pattern:

• Frequently asked questions should each consist of: A question, an answer, a reference to another documentation page

Potential deprecation path

We could keep the FAQ and strip out all its instructions to actual locations in the docs (replacing instructions in FAQ with cross-references), then remove the FAQ from TOC trees and keep it public to avoid breaking incoming links.

The current FAQ is the 20th most viewed page. I don't think it says a lot. It has 1% of all Top 20 hits (51k total, FAQ had 638 views past 30 days).

---

📚 Documentation previews 📚

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

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

[benjaoming]

Using :titlesonly: is an experiment. I'll probably revert it so we can keep a consistent display across the documentation. But the FAQ item is quite a mess with all the FAQ entries in it.

[benjaoming]

In order to make this look less messy, I'll introduce some new top-levels in the FAQ

Building and publishing your project
------------------------------------

Why is my project “failing”?
My build says “passed” but I get a 404 page - why?
Why do I get import errors from libraries depending on C modules?
Where do I need to put my docs for RTD to find it?
What commit of Read the Docs is in production?

Additional features and configuration
-------------------------------------

How do I add additional software dependencies for my documentation?
Can I have access to additional features or settings?
How do I change behavior when building with Read the Docs?
I want comments in my docs
How can I avoid search results having a deprecated version of my docs?
Can I remove advertising from my documentation?
How do I change my project slug (the URL your docs are served at)?
How do I change the version slug of my project?

Big projects
------------

How do I host multiple projects on one custom domain?
How do I support multiple languages of documentation?

Sphinx
------

Does Read the Docs work well with “legible” docstrings?
I want to use the Blue/Default Sphinx theme
I want to use the Read the Docs theme locally
Image scaling doesn’t work in my documentation

Python
------

Can I document a Python package that is not at the root of my repository?
I need to install a package in a environment with pinned versions
Can I use Anaconda Project and anaconda-project.yml?

Other documentation frameworks
------------------------------

How can I deploy Jupyter Book projects on Read the Docs?

[benjaoming]

Yes, I think the experiment of adding top levels is a success. This is how the FAQ looks now after re-ordering questions into top-levels. I haven't worked on the ordering of questions, I think it's fine to leave it somewhat random-looking so people are nudged to skim carefully.

[benjaoming]

At this stage, I think the FAQ section is okay (edit: meaning ready for review). I find it a bit "hard" to spend more time updating the current items when the true solution is to find proper locations for them, typically a new how-to. But our how-to structure isn't done yet.

So I'd like to propose a scope like this:

• A lot of improvements have already been added
• Whatever you see that can be quickly improved, feel free 👍
• Do not get lost in texts from the past here, they are more likely to be removed and it doesn't make sense to update or add more Q&As at this point.
• Edit: If you spot something that's obviously incorrect, it should of course be fixed.

[ericholscher]

Is this ready for review? I got confused by the Not Ready at the top.

[benjaoming]

YES! #9908 (comment) has the latest reflection.

[benjaoming]

The git diff is quite horrible because I moved subsections around into new sections. Sorry. I'm not sure how to make it more pleasant for review.

[ericholscher]

Hrm, I didn't really want to dive into reviewing all the content here, so not sure the best way to review this. 🤷

I think in the future changing content, then restructuring in different commits is probably best. But for now, probably fine to just merge it? 🤷

[benjaoming]

Concluding this PR! Thanks for being gentle about it 🥇