stuartpb
2015-08-01
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.
