Docs: Split Subprojects in Explanation and How-to (Diátaxis)

[benjaoming]

This was originally identified as a "relabel", but I think it's best that we split out the How-to part.

There's a potential to do more here. Is it possible to review and finalize the proposed content and postpone further additions to later?

Note also that subprojects has been added to the glossary in #9676

Refs: #9746

---

📚 Documentation previews 📚

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

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

[humitos]

I'm not assigned to review this PR but I just saw it and added some small comments.

[benjaoming]

Can we say anything clever about creating references to subprojects and using intersphinx?

[ericholscher]

Can we say anything clever about creating references to subprojects and using intersphinx?

It's certainly worth a seealso :)

[benjaoming]

Is there documentation about using Intersphinx main projects==>subproject and subprojects==>subproject ?

Otherwise, I can experiment with it and see if it works...

[ericholscher]

These are good changes. I think it's getting close 👍

We're using main project and source project interchangeably, as well as the note on parent and child. We should definitely standardize this language, and put it in the glossary or style guide.

[ericholscher]

Is there documentation about using Intersphinx main projects==>subproject and subprojects==>subproject ?

Otherwise, I can experiment with it and see if it works...

We have a whole guide on intersphinx that we can just link to. It should just work, but you'd need to configure intersphinx like normal.

https://docs.readthedocs.io/en/stable/guides/intersphinx.html

[benjaoming]

@ericholscher updated this PR with some new changes, including some extra focus on subprojects in the Intersphinx guide.

[humitos]

There are really good improvements in this PR 💯

I think it's not ready to be merged yet, but it's close. I left some suggestions where I had suggestions and comments where I wasn't sure how to make an improvement.

---

I'm not 100% convinced of this type of How-To pages that only explain how the UI works. I'm not oppose to have them, but I'm not sure they are super valuable for the readers and I think they will require a lot of work to keep them updated. On the other hand, the Explanation page works great!

IMHO, these How-To pages work really well when the setup does not only require interacting with Read the Docs UI, but it also needs some extra steps outside Read the Docs (e.g. your DNS provider, changing something in a file, etc). Otherwise, I feel we are doing the work the UI should do for us and duplicating efforts.

Also, note that most of the UI will change with the new templates and we will have to rewrite all these pages to match the new UI elements, pages and workflow.

[benjaoming]

I'm not 100% convinced of this type of How-To pages that only explain how the UI works. I'm not oppose to have them, but I'm not sure they are super valuable for the readers and I think they will require a lot of work to keep them updated.

I really agree with this. But I wasn't actually gonna call it out :) It's more because I think this matches the current formula, i.e. the way this how-to is done matches how other how-tos also look. On the positive side, it's pretty easy to write this, but it would be nice to have a different format all-together. I think we should stick to the "how-to" genre, but we should have more focus on really simple steps, screenshots and a uniform way of describing UI elements and navigation paths.

[ericholscher]

This is looking really close, and I'd love to see it get 🚢'd here soon.

[ericholscher]

Re: @humitos comment about HowTo's, screenshots also don't match across .com & .org currently. It will be better once we ship the new templates.

[benjaoming]

Ah yeah, maybe with tabbed panels, we can find a clever way to fix this in the future.

It's okay to stick with .org screenshots for now, right? Pretty sure that's the general pattern?

[ericholscher]

Yea, it's fine.

[humitos]

@benjaoming

On the positive side, it's pretty easy to write this, but it would be nice to have a different format all-together

I think "pretty easy to write this" is too optimistic 😄 . In particular, giving the non-trivial time it's required to review (113 comments and counting), back and forth feedback on rewording/rephrase paragraphs and discussions happening around how to do it correctly. We are not even counting the time we will require to maintain it in sync with the changes in the UI and the workflow. I suppose we will see how it goes.

[benjaoming]

Ah no, that's true.. none of this writing is easy in general. I meant only that it's pretty easy (relatively speaking) to write the trivial how-tos. Those are the ones where we don't have to think "what do I want to say" or "what order should my message be in". We just have to look at a page and describe how to use it.

...which is also what risks making the value of the how-to very low.