LGTM

I'd suggest starting here by defining what you mean by "Broken dependency" in this context - what kind of error will I be getting that indicates I need this troubleshooting guide?

Is it a failed build in MBS? A module that builds in Fedora's MBS, but fails to build locally? A module that builds, but fails to install? All of the above? None of the above?

While you implicitly explain that below, it helps to start with something that tells people "Yes, I'm in the right place"

Having finished reviewing the rest of the section, the initial version of this can say that it's currently specifically talking the case where a module builds, but fails to install without access to non-modular dependencies.

Problems with build dependencies are trickier in some ways, so it makes sense to defer addressing them to a follow up PR.

@nphilipp Perhaps it would make sense to just merge this as is, and then iterate on improvements to it (including my comments)?

@ncoghlan sounds good to me, will you do it?

@nphilipp Yeah, adjusting this will fit nicely under #76

@ncoghlan bump?

@ncoghlan @langdon

As discussed on Telegram this morning, let's rescope this PR so it covers the follow up work in the area of resolving missing dependencies. In other words, let's hold off on merging this for now and I'll rebase when I'm ready.

@ncoghlan @langdon

I've renamed the page restructured a bit and added new content, please review!

@nphilipp I went ahead and merged this so we can start linking to it from other documents.

My actual review feedback is just https://pagure.io/modularity/issue/80 - we should explicitly call out the option of simply not publishing RPMs that won't install when those RPMs aren't part of the module's public API, and aren't needed as a runtime dependency by any part of the public API.

Oops, I also meant to say: the content looks good to me!

Otherwise I wouldn't have merged it yet :)