Link MDN articles from W3C specs

[dontcallmedom]

When they exist, MDN articles are likely to provide a more approachable form to general developers than W3C specs; as such, it would be useful if W3C specs could link to related MDN articles.

This is probably mostly a matter to find a couple of groups/editors willing to experiment adding such a link in the head of the spec to get started.

Down the line, there are ongoing discussions about redesigning the set of links in W3C specs, and even broader discussion about redesigning W3C specs, which MDN should probably give input to in that context.

[chrisdavidmills]

Adding myself here, to remind me that I need to share this stuff with the MDN team.

[chrisdavidmills]

We are talking about the process by which to add links to W3C specs in #58, so we can probably close this to cut down on duplication?

I am going to copy over the ongoing discussions that MDN should give input to, so we don't forgoet about it.

[dontcallmedom]

maybe we can keep this issue focused on linking from W3C to MDN, and #58 from linking MDN to spec stuff?

[chrisdavidmills]

@dontcallmedom Again, shared this one with the MDN team. I will also send a mail to the spec folk I know in Mozilla to see if they find this in any way interesting.

Did you get any feedback from any of the spec folk about this idea?

[JeremiePat]

Hi! Some quick though on having link from spec to MDN.
In general, I would say: "Sure, why not", but I have some concern:

1. Spec and Documentation do not target the same audience (Spec are for browser implementer, Documentation for web dev) and such links could be considered unnecessary "noise" by some people.
2. Spec talk about the (near) future most of the time where documentation talk about what it is currently. This could make things hard to keep in sync when you want to do a link from spec to documentation as the documentation can be sometimes non existent and won't be until there is at least one (if not two) implementation (documenting something not implemented isn't productive both for writers and web devs).
3. Life cycle of spec and documentation are very different and keeping links in sync can be challenging as the documentation can change without any warning and could no longer fit spec expectations. That is somewhat okay with living spec from the WHATWG as they can be changed as necessary, but with W3C frozen (versioned) spec it could be problematic, even if such link would be of course non normative.

I don't think there are any hard blockers here, but just points that need further investigation.

[annevk]

It seems from OP that the idea would be to add a single link. I'm not sure how that really works since there's usually not a 1:1 mapping like that I think, but I'm not super experienced with MDN. E.g., where would HTML link to?

Would it be appropriate for URL to point to https://developer.mozilla.org/en-US/docs/Web/API/URL or should it point to a page that explains URLs more generally (couldn't find one)?

(Via email @chrisdavidmills mentioned the idea of adding or maybe sharing examples. I think that definitely has some merit, but I'm not sure if that should be discussed here or separately.)

[chrisdavidmills]

So there has been generally quite positive reactions to this idea on the MDN team. And already some good debate here - thanks! To answer some of these points:

First, to answer @JeremiePat 's comments:

1. This is true that they are for different audiences, although I think the links would still be really useful, for example for web developers that end up finding the spec but then want some practical documentation, or spec writers and implementors that want to find the docs that have been written about the spec, check real world uses, and find out if the docs are up-to-date easily. This could faciliate our other plan of wanting to get feedback directly from spec changes on when the update docs. But I think your concern is reasonable - I'd be interested to see if any spec folk share this concern. @dontcallmedom , have you heard any such noises?

2. Yeah. Although I don't expect every spec to do this from their first instance. This would be a nice to have, not an absolute must. And besides, having this as a recognised plus could perhaps spur spec folk on to make some noise about getting docs written and offer help. Maybe?

3. I also agree that this could be a problem. This also relates to @annevk 's point. Again, I don't think the links will be appropriate for every spec. I want to make sure that documentation remains consistent and doesn't change without warning, so I'm hoping this wouldn't be too much of a problem. I also think it might help give us further impetus to pay closer attention to things like consistency and guidelines.

@annevk also gave us some interesting examples to think about. I'd say HTML should just link to the main HTML reference page, but that it would make sense to improve the HTML reference itself, e.g. by including an index of reference pages documenting all the other stuff that HTML specifies besides the elements and DOM interfaces. We already link to the DOM interface for each element from the element pages, but it would be nice to make this more complete. Perhaps we could work together to identify gaps in the HTML docs, and create a plan.

For other APIs, some already have obvious pages to link to, like

https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
https://developer.mozilla.org/en-US/docs/Web/API/Streams_API
https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API
etc.

Where there isn't an obvious single landing page, this is probably a good indication that one should be created. URL is a good example of this. We probably ought to create a https://developer.mozilla.org/en-US/docs/Web/API/URL_API on which we explain URLs more generally, and collect together the features of this API.

[annevk]

Maybe, but, e.g., the Fetch Standard is much more than fetch(). There's a lot more to it, including the CORS protocol, port blocking, redirect handling, etc. And MDN might not want a single entry point for all of that, perhaps, since its audience is different.

[annevk]

(That's also true for URL by the way, the standard describes something much larger than just an API.)

[chrisdavidmills]

@annevk this comes back to the target audience problem, I guess. We can link to stuff like CORS documentation to make sure what's available on the page is complete as possible, but some of the stuff specified simply won't be relevant to our audience, so we won't document it. I guess if we did add these links to specs, we'd have to make it clear that they are web developer documentation.

[JeremiePat]

FWIW, I think that at the moment we should go on a case by case basis. The cases provide by @annevk are super interesting as they force us, collectively, to think more about what is a good spec and what is a good doc for our various audiences.

If there is one thing that this project should emphasis it is the dialogue it opens to improve both spec and doc for the benefice of our readers.

And for that reason, regardless of the points for discussion that have been raised here, I strongly support that initiative.

[annevk]

At least in theory it should all be relevant, since web developers can encounter the standardized behavior, but what's not clear to me is whether you want to organize things in an equivalent manner and be bound by that (due to the cross-linking).

Perhaps an alternative to consider is that you have MDN pages, such as the "Fetch Standard", which briefly explain what the standard is about and where its various features are documented on MDN (if at all). And the standards would link to those pages.

[marcoscaceres]

Perhaps an alternative to consider is that you have MDN pages, such as the "Fetch Standard", which briefly explain what the standard is about and where its various features are documented on MDN (if at all). And the standards would link to those pages.

Alternatively, you might have an MDN page explaining "Fetching resources on the Web" (which covers the things that Fetch conceptually covers, beyond the API).

FWIW, I'm happy to add a link to Payment Request API, and link to https://developer.mozilla.org/en-US/docs/Web/API/Payment_Request_API

[chrisdavidmills]

Alternatively, you might have an MDN page explaining "Fetching resources on the Web" (which covers the things that Fetch conceptually covers, beyond the API).

I'm still not sure that is really relevant to most of MDN's readership. With all the other stuff we have to do, it wouldn't be a high priority anyway. The closest we have on MDN is "Concepts" pages, for example https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Basic_concepts_behind_Web_Audio_API. I guess this could fit under that category. But really the main API landing page should cover the job of showing where everything is documented, etc.

FWIW, I'm happy to add a link to Payment Request API, and link to https://developer.mozilla.org/en-US/docs/Web/API/Payment_Request_API

Cool!

[annevk]

I'm still not sure that is really relevant to most of MDN's readership.

CORS is not? X-Content-Type-Options is not? data: URLs are not? I'd argue there's a fair bit there that's totally relevant to web developers on a day-to-day basis. Perhaps some aspects such as port blocking and redirect handling are less so, but still seem good to have documented (or clearly deferred to the relevant specifications).

[chrisdavidmills]

CORS is not? X-Content-Type-Options is not? data: URLs are not? I'd argue there's a fair bit there that's totally relevant to web developers on a day-to-day basis.

OK, ok, point taken ;-) I guess we have a lot of this stuff mentioned/documented in other places, but it'd be great to have an article written that ties it all together in the context of fetches and explains how it all works together.

I just need to find someone to write this now ;-)

[marcoscaceres]

My understanding is that there are basically two (or more) user types:

1. Folks who google "the foo API", jump into MDN, copy, and get out in less than 30 seconds (probably 95% of users).
2. Folks who want to know how stuff works.

Folks from 1 can transition to group 2 when the page points to further reading, or they see something interesting.

I just need to find someone to write this now ;-)

Can we ask one of our awesome communicators, like Lin Clark? Fetch (and it's related concepts, security model, etc.) is kinda fundamental.

[chrisdavidmills]

Folks from 1 can transition to group 2 when the page points to further reading, or they see something interesting.

Or quite often people can go from 2 to 1, depending on what kind of learner you are.

Can we ask one of our awesome communicators, like Lin Clark? Fetch (and it's related concepts, security model, etc.) is kinda fundamental.

Lin would be a great choice. Her lucid prose and cartoon treatment would work really well, applied to fetch. I'll give her a shout and see what she thinks.

[chrisdavidmills]

I think this is happening now, on at least some specs that I've seen. Can we close this one?

[dontcallmedom]

yes - the infastructure is out there, it's "only" a matter of getting groups to adopt it