Add links to troubleshooting documentation in exception messages

[tillig]

Problem Statement

Despite having reasonably clear error messages for our exceptions, there continues to be an... inordinate... number of StackOverflow questions that are all effectively titled "Autofac DependencyResolutionException" (which isn't a question and largely indicates folks haven't actually tried fixing it, but I digress). It's unclear whether the message is still confusing to people or whether it's a case of "TL;DR."

Desired Solution

It may be helpful to:

• Create documentation pages for troubleshooting/explaining specific well-known cases, like:
  • Missing a dependency registration.
  • Error during instantiation.
• Create explicit bit.ly links to these pages.
• Include the links in the associated exception messages to get people right to the documentation.

Alternatives You've Considered

• Make the messages more robust: Puts the information right where it needs to be, but I think the messages and inner exceptions are getting long enough that folks have stopped actually reading.
• Link to existing documentation: While we do have some good docs, it might be good to have more "purpose-built" docs for specific situations to help folks that are overwhelmed by the quantity of things that may be going wrong. It might be good to restructure the existing stuff so we don't have duplicate info to maintain if we add these new docs.

Additional Context

It doesn't have to be bit.ly, but:

• We probably do want to use a link shortener so the underlying link can be changed if needed without changing the code/exception message.
• Whatever link shortener we pick should allow us to change the link later. Some are one-and-done and you can't change the underlying link.
• It'd be nice if it was a custom Autofac-related domain, but I'm not sure we have anyone who wants to both buy a domain (plus keep it going) and pay for the "custom domains" package on a link shortener service.

[alistairjevans]

Instead of using bit.ly links, could be not just create pages on autofac.org that redirect to places in our docs?

Pretty trivial to do I believe with a custom Jekyll layout file, and a meta tag.

[tillig]

Yeah, I don't have a strong preference of how it gets done, I was just interested in the idea of being able to provide direct doc links to common issues.

Though, admittedly, I feel like an actual 302 is somewhat better than an HTML-based meta redirect, simply because non-browsers can deal with it a little easier (if that's a use case). curl and Invoke-WebRequest and similar things will follow 302 but not HTML redirects.

[alistairjevans]

I've taken a look at options for the shortener. bit.ly will provide the functionality we need 'for free', including creating links with custom path content, e.g. http://bit.ly/autofac-scope-docs (link works). The only really obvious downside is that you can't add other users to manage those links, so we would have to share creds (not super ideal, but manageable).

One alternative that shows promise is setting up 'Exact Redirects' on readthedocs itself. We should be able to set up https://autofac.rtfd.io/help/di-exception (or similar) to point where we want, and that would end up on the right page. Benefit of this approach is that we don't need to create any new accounts or anything, and our links stay under the same domain as our docs. Plus, with their rtfd additional domain, the links are still pretty short.

Only issue with the ReadTheDocs approach is that...it doesn't work on our project, but does appear to work on my personal fork. I've raised an issue with them to ask why that might be. If the answer is straightforward, this approach is probably my preference.

[tillig]

Oh, I didn't know about the native RTD version. Keep me posted on what you find, I like that one, too.

[alistairjevans]

According to the ReadTheDocs people, our docs are set up as a translation of a different set of docs, autofaccn? @tillig, do you know what that's about, I don't have access to that autofaccn project?

[tillig]

👀 UHHHHHH noooooo that doesn't seem familiar at all. However, I do see on the dashboard that's how it's set.

Maybe something in the config file? I'll look around a bit.

[tillig]

I'm not seeing anything like that anywhere in the config but... @alexmg @nblumhardt could autofaccn be an artifact of configuring the custom domain name for docs? Seems like the cn part overlaps with CNAME and maybe it's misinterpreting that? I don't have access to our DNS setup so I don't know if it's something we created or something that possibly got created by accident by the RTD folks.

I do recall there was a lot of shuffle when they moved from .org to .io so this could be a remnant of that. I have also seen how docs.autofac.org redirects to autofaccn.readthedocs.io and I always sort of wondered what that cn part was but just... didn't care much.

[alistairjevans]

To quote from the RTD issue:

if you don't have access to that other project I can remove the relationship (there was an old bug that allowed users to set projects as translation of others without having the same owner).

[tillig]

Yes, let's decouple that.

[alistairjevans]

My only concern might be that any existing references in other people's blog posts or similar generated content will break in that event?

[alistairjevans]

If possible we sort of want to invert the relationship.

[tillig]

We might have some link breakages, yeah, but we may be able to set up some sort of other project and redirect or something. Given we're somewhat stuck on other RTD features because of this, I'd somewhat rather rip the bandage off and figure out how to fix it than try to leave it alone and try to add more workarounds to the mix.

[alexmg]

could autofaccn be an artifact of configuring the custom domain name for docs?

The DNS has two A records pointing to Cloudflare IP addresses. I think only @nblumhardt has access to the configuration in Cloudflare.

[nblumhardt]

Odd! I've never encountered autofac.cn or autofaccn that I can recall. Sounds like a user may have set that field via the bug mentioned previously. Just give the word if we need anything reconfigured, easy here.

[nblumhardt]

Ah, and 👋 hey all, hope you're all doing well! 😎

[alistairjevans]

Right, turns out someone once indicated that our site was a translation of there's (somehow?); don't entirely understand, but you can see the details here:

readthedocs/readthedocs.org#8134 (comment)

I'm going to suggest we give the original forker(?) the chance to fix it so redirects don't break, but if that doesn't pan out we'll just pull the plug on the connection between the two.

[tillig]

I think that's a reasonable plan. Let me know if there's anything I can help with. What a cluster.

[alistairjevans]

Right, so this has been an entertaining morning, during which time our docs were entirely broken for an hour or two.

Basically, that original owner of the autofaccn project just deleted the project entirely, which led to our docs getting stuck in a redirect loop. I figured out the redirect loop was down to docs.autofac.org being set as the Canonical name (which it hasn't really been for years, because of the translation snafu).

I then claimed the project name autofaccn in the name of autofac by creating a blank project (https://github.com/autofac/CnRedirectPlaceholder) and creating that now-available project under our ownership.

I've put in place a redirect that will take an existing autofaccn link (e.g. https://autofaccn.readthedocs.io/en/latest/getting-started/index.html) and push the user to the right place, but I can't do that for the root landing page, so I've just had to put a "things have moved" link at https://autofaccn.readthedocs.io/).

This isn't ideal, but at least existing links from StackOverflow answers won't break.

Feel free to read the blow-by-blow: readthedocs/readthedocs.org#8134 (comment).

As @tillig said, a bit of a cluster.

[tillig]

😩 It's always something. Good work tracking this down! I think we can live with the simple main page you have there. Maybe at some point we can figure out how to add something like this redirect plugin to the site to handle the main page. In any case, is call this a win.

[alistairjevans]

@tillig, do you know who controls the DNS for autofac.org? We need to configure docs.autofac.org to CNAME to readthedocs.io as per https://docs.readthedocs.io/en/stable/custom_domains.html#custom-domain-support.

Otherwise docs.autofac.org will keep getting stuck in an infinite redirect loop.

[tillig]

It's @nblumhardt - he mentioned a while back if we ping him for something (ping!) he might be able to help out.

[nblumhardt]

Done! Might take a short while to propagate - let me know if it needs any tweaking 👍

[alistairjevans]

Thanks @nblumhardt, looks good. 👍

[tillig]

I think everything here is wrapped up and merged. This should show up in exception messages in the next release.