New page on filing browser bugs

[Josh-Cena]

Fix #28312. This has the nice effect of getting rid of "how-to" guides in ARIA, because currently this one is extremely thin and isn't even a guide. The placement of the doc is tentative, because I can't find a better place for general web stuff.

[github-actions]

Preview URLs

• /en-US/docs/Learn_web_development/Getting_started/Web_standards/How_browsers_load_websites
• /en-US/docs/Learn_web_development/Howto/Web_mechanics/File_browser_bugs
• /en-US/docs/Web/Accessibility/ARIA

External URLs (13)

URL: /en-US/docs/Learn_web_development/Howto/Web_mechanics/File_browser_bugs
Title: When and how to file bugs with browsers

• https://bugs.opera.com/wizard/ (1 time) (Note! This may be a new URL 👀)
• https://bugzilla.mozilla.org/ (1 time) (Note! This may be a new URL 👀)
• https://codepen.io/ (1 time) (Note! This may be a new URL 👀)
• https://github.com/nvaccess/nvda (1 time) (Note! This may be a new URL 👀)
• https://github.com/tc39 (1 time) (Note! This may be a new URL 👀)
• https://github.com/w3c/csswg-drafts (1 time) (Note! This may be a new URL 👀)
• https://github.com/whatwg (1 time) (Note! This may be a new URL 👀)
• https://issues.chromium.org/issues (1 time) (Note! This may be a new URL 👀)
• https://jsfiddle.net/ (1 time) (Note! This may be a new URL 👀)
• https://support.freedomscientific.com/Forms/TechSupport (1 time) (Note! This may be a new URL 👀)
• https://webkit.org/reporting-bugs/ (1 time) (Note! This may be a new URL 👀)
• https://www.freedomscientific.com/products/software/jaws/ (1 time) (Note! This may be a new URL 👀)
• https://www.nvaccess.org/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2025-10-01 19:01:47)

[dipikabh]

I was taking a quick look to check if there's another place to add this info - haven't found one yet. Might be good to tag @chrisdavidmills since he's the most familiar with all the corners of the Learn area and may have a better suggestion.
I also find Web mechanics and its child pages grouped under "How to" somewhat odd. Maybe Chris can shed light on this as well.
In fact, the new page "How to file bugs with browsers" may end up being the only real how-to there.

I'll come back with a more detailed review. In the meantime, what do you think about adding a "See also" to How browsers load websites to include a link to the new page?

[chrisdavidmills]

@Josh-Cena A few thoughts for you.

In terms of placement, this is quite reasonable, imo.

[chrisdavidmills]

I was taking a quick look to check if there's another place to add this info - haven't found one yet. Might be good to tag @chrisdavidmills since he's the most familiar with all the corners of the Learn area and may have a better suggestion. I also find Web mechanics and its child pages grouped under "How to" somewhat odd. Maybe Chris can shed light on this as well. In fact, the new page "How to file bugs with browsers" may end up being the only real how-to there.

Yeah, a lot of them are not really howtos, but I really wasn't sure where else to put them. A lot of them are old articles that have been around since the Learn area was first started. I just stashed them here for now, but we ought to figure out what to do. They are really "common questions", but I wanted to try to use the "Howtos" format as that is what we are doing in other topic areas.

I'm wondering if we should add a "common questions" section to contain these alongside the "Howtos", or reformat them to be howtos, or something else. Some of them could probably even be deleted to save repetition or merged into other articles.

[Josh-Cena]

Reordered the sections a bit. Reconciling browsers, docs, and spec is muddy waters because any of them could be incorrect, so this can be easily confusing😅

[chrisdavidmills]

@Josh-Cena Nice work, this is looking much better. I've made a few more language suggestions, including adding a few H3s into the main section to break it up a bit, but this is comparatively minor stuff now that the structure is getting there.

[dipikabh]

Thanks a lot for adding this page, Josh.

Thanks also to Chris for reviewing! I'm leaving a +1, but Chris may also want to take another look before merging.

[dipikabh]

I think this is what we're trying to say...added some connectors to build the flow.
I found the last sentence a bit snarky, I've tried to soften it a bit.

Suggested change

Before filing a browser bug, you should make sure that the bug is real. It could be in one of four places: your code, the documentation, the browser, or the specification. Generally, the specification is the most credible source of all; browsers and documentation both follow the spec and can be wrong. As for your code...well, the quality depends on you.

Before filing a browser bug, you should confirm that it's actually a bug in the browser. The problem could come from one of four places: your code, the documentation, the browser, or the specification. It's important to rule out the other possibilities before reporting a bug to the browser. Generally, specifications are the most credible source of all; browsers and documentation both follow specifications, but can still have mistakes. As for your code, it's always worth double-checking for logic and typos before assuming it's a browser bug.

[Josh-Cena]

It's really meant to be a little snarky. The implication is "your code is the most likely to be incorrect of them all" :)

[dipikabh]

I guess "before assuming it's a browser bug." retains a tiny bit of snark

[chrisdavidmills]

A few more minor comments, but I'll approve this now. I don't think I need to look at it again. Nice work, @Josh-Cena!