Replies: 1 comment 5 replies
-
|
If a feature has 10 bugs in different browsers, then the page would look more like a bug report than a feature page. |
Beta Was this translation helpful? Give feedback.
-
|
I do also like @captainbrosset's point about documenting the real state of things. I wonder if there's any appetite for footnotes or annotations that link to a section like this ( edit: i.e., some other mechanism that's not as interleaved with content as "this is the feature, this browser handles is this way, the other browser has it behind a flag" - if there was a way to display this information by means of annotations, that could be filtered out / updated via automation without prose rewrites, it would be nice. |
Beta Was this translation helpful? Give feedback.
-
|
Obviously interleaved comments right where the incompatibility happens would be more useful for readers but we know this is unmaintainable. I hadn't considered a footnote solution linking to a section on issues. That at least might be maintainable because all the differences are in one section. If it were me, such a section would be inside compatibility section. We would need to consider disclaimers, dates, bug links and other tricks to give hints when the material needs to be revisited. |
Beta Was this translation helpful? Give feedback.
-
Yes, this is surely the right place to keep it (if we want it in content at all, that is). |
Beta Was this translation helpful? Give feedback.
-
|
Just for the sake of illustration, this is the footnote support in GFM (docs/blog): Browser-specific settings are enabled, such as blocking all cookies, private browsing mode[^1], automatic cookie deletion on close, etc.
## Browser compatibility
{{compat}}
[^1]: In Firefox, Service Worker APIs are hidden and cannot be used when the user is in [private browsing mode](https://bugzil.la/1320796), or when history is disabled, or if cookies are cleared when Firefox is closed.i.e.;
Footnotes
|
Beta Was this translation helpful? Give feedback.
-
|
I quite like that. Even if we can do this though, we should still do it only where it really matters - and provide ourselves with enough hints/issue links etc to allow us to know when things have likely changed. |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
This is a slightly-cleaned-up version of a discussion thread in Slack. I'm not really sure what to make of it yet, so I'm mostly sticking this here before Slack eats it, although it would be good to try to make a proper guideline out of it at some point so people like me stop asking.
Original question
Recurring question: when should/shouldn't we describe browser bugs/support differences in MDN content pages, rather than just leave them in BCD? We usually say "document the spec and leave browser differences to BCD" but it bothers me that this isn't very helpful, partly because BCD - as it is rendered in MDN pages - isn't great at surfacing these differences, and partly because BCD doesn't have a very rich language for expressing them. So from a usability pov I'm always drawn to document them in the page. The case at hand is mdn/content#38132 , which seems to want to capture a Safari bug (https://bugs.webkit.org/show_bug.cgi?id=77998). I'm tempted to include this in the page, for the reasons above (I don't think the current wording on the PR is ideal, but that's a separate question). I think we should also document the bug in BCD. But should we only document it there?
@Josh-Cena
I think in this case we should move their second paragraph to BCD, since it's literally just "affected by zoom".
However a content note is also necessary for the first paragraph, saying what the expected interaction with zoom is, with a note saying "some browsers are not conformant; check the BCD".
Something like:
Because I know as a fact that devicePixelRatio also interacts badly with page zooming on Safari—in which case https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio mentions the typical zooming interaction, and BCD notes Safari as partial implementation. I'm happy to drop the "browsers are incompatible" note in content, but what's expected should be documented.
@hamishwillee
FWIW
Upshot I'd rather use the tools we have and be accurate than attempt to integrate in the body of text.
@OnkarRuikar
Documenting browser bugs in content doesn't sound good. Shifts focus away from the main content. If it is a bug, we could add the bug link to the 'See also' section, with one liner, instead of a big para in the content. This will save us from future corrections in the page content. When people will follow the bug link they'll know if the bug has been fixed or not.
If the bug doesn't exit on browser sites then we can ask the pr author to report there and provide a link. Or we could report the bug ourselves and update the PR if it's a really a bug.
@captainbrosset
I know this is quite tricky, but I tend to agree with Will. Documenting spec only means documenting what we want the platform to be, not what it currently is.
Documenting the real state of things is much harder to maintain/validate. But if we can keep it up to date, then is also vastly more useful to web developers. The right thing to do is probably in the middle somewhere, and I think that's what MDN already does. For example, the docs for customizable built-in elements has a banner saying that Safari won't implement it. That's not spec, that's browser reality. Case by case banners like this make sense to me. I wouldn't want to have to read an entire MDN page, familiarizing me with a technology, following syntax and examples, only to find out later that I can't use it cause it's not really implemented as described in all browsers.
I think web-features/baseline should help here. Ideally, BCD would help, and it already has the structured data for it. But BCD makes no decision as to what's blocking or not blocking. While web-features does. Web-features takes one or more BCD keys, groups them into a feature that makes sense to developers, and then makes a (possibly manual/editorial) decision as to whether the feature is supported or not, and where. So I guess what I'm saying is:
is)@Josh-Cena again
In case my opinion wasn't clear:
I think
window.devicePixelRatiois a good model to follow.Beta Was this translation helpful? Give feedback.
All reactions