Consider relaxing specification URL linting rules

[ddbeck]

248 suggested that maybe we're too aggressive with specification URL linting. Right now, we require that spec URLs have fragments, even if it's not necessarily the best target:

But also, for "HTML.md", the best link seems to be just https://html.spec.whatwg.org/multipage/, so I worry that we are making the content less good to please the linter, and we might be better off to relax the linter's requirement for links to contain fragments.

Originally posted by @wbamberg in https://github.com/mdn/stumptown-content/pull/248#issuecomment-554553750

[ddbeck]

@Elchi3 would love to have your thoughts on this

[Elchi3]

Relaxing the linter would probably mean that we will end up not deep linking correctly into specifications sometimes. On the other hand, the case of a top-level document (like html.md) where we could just link to the spec without deep link, is quite rare I would say. So, imo this would relax the linter for the benefit of very few cases only, but at the same time it would make possible more cases slipping through, where we should provide a deep link.

[wbamberg]

Relaxing the linter would probably mean that we will end up not deep linking correctly into specifications sometimes. On the other hand, the case of a top-level document (like html.md) where we could just link to the spec without deep link, is quite rare I would say. So, imo this would relax the linter for the benefit of very few cases only, but at the same time it would make possible more cases slipping through, where we should provide a deep link.

It's certainly true that most links will include fragments (although for example many of the top-level Web API pages (e.g. https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API, https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API) are also going to be affected.

But there's a difference between "the linter doesn't help you make the content better" and "the linter forces you to make the content worse". If someone files a bug that, say, https://fetch.spec.whatwg.org/ is a better link than https://fetch.spec.whatwg.org/#contents, we have to close it saying "yes, we know, but we can't fix it because of our linter".

Of course the way to have our cake and eat it is to allow authors to disable the check:

# stumptown-linter disable require-specification-fragments
specifications: https://fetch.spec.whatwg.org/

...which seems like a lot of work to support in a generic way, but might be possible to implement for for individual cases as they come up.

Anyway, just my 2c. I won't press the matter.

[Elchi3]

Useful 2cents, Will! I guess only more experience with this will tell us if we should be more lax or not.

@sideshowbarker You've implemented spec_url in mdn/browser-compat-data and all spec_urls require an anchored link (in fact my implementation here is highly inspired by your work in BCD). Has it been problematic / unuseful that you always require fragments?

[ddbeck]

Another idea that I had while looking at the implementation again: we could relax the anchor requirement by allowing empty anchors (i.e., URLs that terminate in #). That'd catch the case of pasting in fragment-less URLs, but allow the option of not deep linking. Maybe that's good enough?

[sideshowbarker]

@sideshowbarker You've implemented spec_url in mdn/browser-compat-data and all spec_urls require an anchored link (in fact my implementation here is highly inspired by your work in BCD). Has it been problematic / unuseful that you always require fragments?

No it’s not been problematic — in fact, it’s been the opposite; that is, it’s been useful (in the automated build system I use for generating https://github.com/w3c/mdn-spec-links data) in helping to identify MDN articles with Specifications links that don’t point to specific parts of specs but should.

That said, I can imagine there being exceptions where a contributor intentionally doesn’t want to link to specific section — so I agree that providing some kind of opt-out for those exceptions makes sense.