A partial archive of discourse.wicg.io as of Saturday February 24, 2024.

Resurrecting webplatform.org


Continuing the discussion from A "who-does-what-where-and-has-what-say" primer:

While it is true that webplatform.org hasn’t received enough attention and that MDN still has the clearest, most routinely accurate documentation available for web development, I don’t really agree with the sentiment that a new documentation corpus (whether it be http://docs.webplatform.org or a new project altogether) should be abandoned, for a couple reasons:

  • The MDN is tied to Firefox, in more than one sense.
    • When you do a search for general terms like “image”, approximately half the results that come back are for arcane Firefox-specific formats like XUL (about half of which are obsolete/deprecated to some degree). This makes it harder than it should be to find even basic information related to the Web as a whole. (When I did a search for “service worker” just last week, the first result I was given wasn’t https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorker but some page about Mozilla’s “Social API”.)
    • To the unacquainted, a Mozilla-tied documentation source doesn’t appear to be as “legitimate” as a neutrally-named site like w3schools (ironically). I’ve seen a support technician assume I was using Firefox because I sent him a link to the MDN page on the Notifications API in my bug report.
  • It’s not terrible to read, but it is terrible to edit.
    • The Kuma engine powering it is replete with many failed experiments of its own (this time last year, the only way to log in was to use Mozilla’s Persona service).
    • Page content, rather than being in a simple, easy-to-work-with syntax like Markdown, is stored as raw HTML, with a fossil layer of differing stylistic approaches several layers deep (inline styles and incompatible classes abound) sprinkled haphazardly throughout each document. The tooling “solution” to this has been to implement a WYSIWYG editor for page content, which is as perennially frustrating and pollution-prone as every other WYSIWYG HTML editor ever written.
  • Its content is actually fairly inconsistent, with pages including vanity projects like in-line libraries sixty lines long in the page, rather than linking to a standalone script/polyfill hosted on GitHub (for example, see the page for document.cookie).
  • Its “browser support” matrices are redundant with caniuse.com (though, frustratingly, MDN’s matrices are usually more detailed and up-to-date than caniuse’s), and it doesn’t track the outlook for future support from each vendor the way https://www.chromestatus.com/ does.

This is what I really want to see for the Web Platform documentation landscape:

  • A single, W3C (Community Group or higher)-backed (and otherwise independent) “standard” documentation base, oriented toward end developers rather than browser implementors, that gives a plain-language explanation of what standard (and universally non-standard) behaviors the standard platform supports at the interface level. (The specs are great and everything but, as @jaffathecake observes, when you’re just trying to write web content, they’ll make your eyes bleed.)
  • More opinionated / goal-oriented / bigger-picture guides linking into this, on HTML5 Rocks, CSS Tricks, Wikibooks, personal blogs, and even just unadorned GitHub repos (and maybe some kind of Discourse for page architecture, like how the Programming Stack Exchange used to be), with an active W3C/Web Platform Showcase blog collecting and linking out to these on a weekly basis (something like the Cooper Press newsletters without the ads, or like Google Developers LazyWeb video series without the video).
    • Something like a “Web Platform Badge of Approval”, that says the official Web Platform Community Group reviewed a post and deemed it very good (on a certain review date, so people don’t get confused why the vendor prefixes the API was listed as having in 2012 aren’t working), would be a good signal to developers, too.

Because “been there done that”. See A "who-does-what-where-and-has-what-say" primer

I won’t fault anybody else for trying to make an alternative to MDN but if they do they shouldn’t be surprised to get a lot of “don’t count me in” responses—especially from people working on browser-engine projects or who’ve otherwise been involved over the last 10 years or whatever with work on developing the core set of Web-exposed interoperable technologies that we all want documented and explained (as MDN attempts to).

@stuartpb all the problems with MDN that you’ve outlined would seem to be fixable with changes to MDN. In my experience, the people leading the work on MDN are highly responsive to feedback and suggestions for refinements. So I’d personally suggest that instead of trying to get an alternative off the ground, the energy would be better spent getting involved with MDN and helping to make it better.