Park resolutions to common build problems in FAQ

[benjaoming]

While investigating a question about a build error, I went through a bunch of trial-and-error and noted the common reasons for various git errors.

Questions for common build errors could benefit from having a place in the documentation? For now, this could be in the FAQ. However, we could also add a Troubleshooting section.

---

📚 Documentation preview 📚: https://docs--9472.org.readthedocs.build/en/9472/

[humitos]

However, we could also add a Troubleshooting section

I like this idea. A lot of the FAQs currently are related to builds, so we should have a "Troubleshooting Builds" page probably. Besides, it could be split into sections depending on "where in the build the error appeared". All the errors from this PR could be under the "Clonning" section, for example --following the states from the Build process.

That said, the FAQ page will keep all the other questions that are note related with the build process itself.

[agjohnson]

Yeah, I think a separate page is a better resource. The FAQ is a bit of a parking lot of content we didn't want to create a dedicated page for, and much of that content should probably be moved to more relevant pages, where it can be found and indexed more readily. A lot of this content is probably missed, as users probably don't think to head to our FAQ page to debug builds/etc, or aren't being pointed to it from search queries.

Also, debugging builds is an important enough topic that we should cover it in a dedicated doc. There is a lot we could say on the subject.

[benjaoming]

@agjohnson Would feel fine about moving it somewhere else. I didn't immediately find good answers regarding adding new sections in the documentation. I haven't worked much with the overall structure of the user docs and am under the impression that we could do some Diátaxis on it 🪄

Can you help to propose a new location for now and I'll gladly put/park it there? :)

[agjohnson]

Aye, it's isn't quite clear where I'd go to author this, or where I'd look for this information as a user -- based on the TOC and main navigation at least.

So I suppose two options:

• Split out a TOC captioned section for "Support"/"Help"/similar, to include "Site support" (under Features currently), and maybe FAQ (also under "Features" section currently).
• Include troubleshooting information right on the build process page. We follow this pattern in a few other places, like here

There are points to both, though. Keeping support along side the implementation notes for users seems to make sense, though I also feel like that GitHub troubleshooting is a section I have to manually link to users the most 🙃 -- perhaps it's not as easy to find as we think.

If users are dropping directly in our docs to troubleshoot, then they might sooner find a "Troubleshooting" doc at the top level.

Both seem like okay options to me, really

[humitos]

Include troubleshooting information right on the build process page. We follow this pattern in a few other places, like here

Including a small section called "Troubleshooting" in the build process page, sounds 💯 . However, IMO, that section should link to a completely different page that explains in deep all the possible cases and their solutions (the content of this PR 👍🏼 ). Otherwise, I think we will "contaminate" the Build Process page with a lot of information that most users won't need to read.

[benjaoming]

There doesn't seem to be a perfect fit :) But the input is really valid! There is already a similar Troubleshooting in the Pull Request section.

Supposing that we can move forward with a Diátaxis-inspired navigation restructure, we can perhaps relax the requirements for placing new sections like this one?

I would like to propose that moving forward with this PR could be done like this:

• Merge as is, knowing that it can get better
• Open a new meta issue for navigation restructures, making note that this is some of the contents that will benefit from such.

[benjaoming]

(the contents of the PR were finally consolidated with some new support case troubleshooting, hence why it was previously stuck as a "draft")

[agjohnson]

Just some casing issues I noticed.

[ericholscher]

@benjaoming I'd say we just add a new page, instead of merging as is. I don't think it matters where we put it. I think we could easily put it into the Features list for now, similar to the FAQ. So Features > Build Troubleshooting, similar to the other build-related pages there.

[humitos]

I agree with Eric that creating a new page and merge it is better 👍🏼

[benjaoming]

It has been moved :)

I made another final adjustment to the text: Two people within a week had issues (re-)adding the SSH deploy key because they were adding the SSH key from RTD as their own personal SSH key. Therefore, the troubleshooting guide is now very specific about where to add the deploy key.

[ericholscher]

This is great. Gonna merge it to get it into the world next deploy, but we should probably also start to make some Front quick replies that link to these as well 👍