Respect example domains

[Jxck]

Example domains

RFC 6761 Specifies reserved domain for Example usage in documentation.

https://datatracker.ietf.org/doc/html/rfc6761#section-6.5

• *.example
• *.example.com
• *.example.net
• *.example.org

MDN content should respect these usage in their document, sample code, sequence images etc.

Why

There are tons of documents in MDN which uses Real Domain as example usage. for example.

https://github.com/mdn/content/blob/main/files/en-us/web/security/same-origin_policy/index.md?plain=1#L21

| URL                                               | Outcome     | Reason                                           |
| ------------------------------------------------- | ----------- | ------------------------------------------------ |
| `http://store.company.com/dir2/other.html`        | Same origin | Only the path differs                            |
| `http://store.company.com/dir/inner/another.html` | Same origin | Only the path differs                            |
| `https://store.company.com/page.html`             | Failure     | Different protocol                               |
| `http://store.company.com:81/dir/page.html`       | Failure     | Different port (`http://` is port 80 by default) |
| `http://news.company.com/dir/page.html`           | Failure     | Different host                                   |

in this case, company.com is a real domain which serves web site. (fortunately store. / news. has no A record in this case)

imagine if your sample code uses some real domain like this, and document user try it by themself with copy-paste. Traffic can be happen to the server of domain owner. If the tons of user doing it at same time, it can be a kind of small DOS attack.

Example domains are safe for documentation use. Actually example.com, example.net etc are hosted by IANA. But it's allowed to use freely.

And also, if you require multiple domains for describing OIDC dance sequence, 3rd Party Script diagram etc etc.
It's better to choice not idp dot com / rp doc com / ads do com etc but idp.example / rp.example / ads.example etc.

Proposal

There are some usage for real domains exists. They exists before yari and I think reviewer blocking them now.
I'd love to help find-and-replace work for existing usage.

And I don't know current linter for content blocks real domain usage, but it's not, better to have it (I don't know linter has such features thought).

[bsmth]

Thanks a lot for raising this one. There is a preference to use the domains listed in the RFC and the efforts to change those in the examples have been ad-hoc such as the following:

• chore: use example.com as an example domains content#15551

And when files have been changed and there is an opportunity to update existing examples, we try to do this in parallel. It would be great to track remaining uses that occur inside code blocks and change those remaining.

And I don't know current linter for content blocks real domain usage, but it's not, better to have it

That's a good point. Sometimes we may want it to point to real domains as there are legitimate reasons to do this, such as towards domains operated by MDN. Still, having an automated check in place would be great.

[bsmth]

See also: mdn/interactive-examples#2650

[Jxck]

#2709 was a work align with this issue, but it's been closed by @estelle .
Is that a decision by MDN ? don't we require more discussions to make agreement not only single persons favorite style but guideline for Open Web Docs ?

[estelle]

When the point of a page is to explain how to use an email, domain names, or components of a URL, we should prefer to use the example.com domain in the examples. This does not mean we should change every MDN example to only include example.com as a domain.

Yes, please update any email address to an example.com email address. We don't want some random made-up domain getting tons of spam. That said, when updating email addresses to reflect the example.com domain, make sure the start of those email addresses are not English-only, male-only, etc. names; for example, include names from all the world's regions, not just johndoe@ or similar. We want to be inclusive in our examples.

When it comes to domain names, we can and must include diverse domains in our examples.

To teach a topic, we need multiple different examples. We also need examples to be as fun, engaging, and inclusive as possible. When teaching how to parse a domain name, same-origin-policies, XSS, etc., we can and often should use example.com,. However, when explaining how to sort a table, we can and should make the example interesting, inclusive, etc. Using the Mexican women's soccer team would be a great example, with a link to the resource for the team. This example is likely preferable to one that conforms to RFC 6761 for the sake of conformance.

The suggested edits must improve on the original for a PR to be approved. #2709 was closed without merging as the original content was better. Please don't change all the examples pointing to firefox.com, mozilla.org, wikipedia.com, etc., to point to example.com. Changing mozilla.org or wikipedia.org to example.com just for the sake of conforming to RFC 6761 is not, in many cases, an improvement.

[chrisdavidmills]

I agree with this, completely. I also don't think this is important enough to spend a huge amount of time changing all the URLs around MDN. There is much more useful work that could be done.

[chrisdavidmills]

In yesterday's OWD writing-docs meeting, we discussed this one, and agreed that @estelle's take on this makes sense. It makes sense to use example.com when explaining how to use an email, domain names, or components of a URL, but this should not be done everywhere. To do that would make MDN less inclusive and interesting.

Also, any changes to use example.com should be done as we encounter them. There is no need to spend lots of time hunting these instances down. There is more important work to be done.