There’s been a lot of interest in yesterday’s release of Google Doctype. The primary focus of the release is on documentation (specifically “documenting the Open Web”) however there’s also two extra, hidden, additions: A Google-released JavaScript library and an Open Web test suite. Let’s break down the parts of this release.
Documentation
On the main Google Doctype site they provide a link to Browse Google Doctype which takes you to a JavaScript-laden site through which you can read the various articles that they provide. If, instead, you’d prefer to read something a little more static (and sanely linkable, bookmarkable) you can just go straight for the Google Doctype Wiki instead.
The documentation falls into 2 realms:
DOM and CSS
These are sort of API references to all the DOM and CSS properties. However, browsing through, they don’t seem to be terribly useful. At best, these references are programmatically generated (seeded with initial values). It’s not completely clear what its setting out to achieve but my guess is something like “if we put all the information in a wiki, maybe people will come and fill it out,” which seems a little awkward (especially since it’s already been done before).
The primary original content provided by this reference is related to the ‘browser compatibility’ section of each item. For example, examine the background-postition CSS property page. There’s a whole bunch of information being tested for – and a whole lot of ‘N’s in the columns – in fact there’s even a couple rows that contain nothing but ‘N’s. This says to me a couple things:
- When every browser fails a test then you’re probably testing the wrong thing.
- The fact that the actual return values aren’t shown makes this extra frustrating (every browser fails background-position: left – but what do they fail with? what are they returning, instead?).
- There doesn’t seem to be any attempt to test for compliance. Overwhelmingly the test values appear to be “the value that goes in should be the value that comes out” – which is rarely the case. Granted, it’s much easier to write tests of this nature (just generate them programmatically) but the end result doesn’t really help anyone.
How-To Guides
The final portion of the documentation centers around a number of articles relating to JavaScript/DOM programming.
A number of these articles are quite good (such as the Web Security section and a couple of the other articles). However, the rest of the articles are quite… confusing. They appear to be documentation for methods of a Google JavaScript library, however they’re presented as Copy-and-Paste examples that developers can use. I think most developers will be quite disappointed when they find out that it’s not possible.
On the article pages the Google JavaScript library is never mentioned, nor linked to. You can eventually find it if you go to source, browse the SVN (to the right directory), and download the individual files of the library.
I think I can safely say that this is the first time that documentation for a JavaScript library has been released before the library itself.
Google JavaScript Library
The second portion of the Google Doctype release was the public unveiling of the (for lack of a better name) “Google JavaScript Library.” It, currently, only existing in Google SVN. There doesn’t appear to be an API reference, either – beyond the various articles provided in the above How-Tos.
Digging through the code there appears to be a huge depth of coverage for some… rather obscure JavaScript topics. If anything has been shown during the last couple years of JavaScript library development (in that the functionality that users have been asking for, and using) is that DOM traversing, DOM manipulation, Events, Ajax, and Animations are fundamental. While the Google JavaScript library does provide some DOM manipulation and Events they completely ignore all other aspects of JavaScript development. Instead they delve off into the land of object traversal, string manipulation, math helpers, and data structures.
If I had to pick a library that this one was closest to I’d have to say MochiKit. I wasn’t very surprised then to find out that the Google JavaScript library’s DOM helpers were heavily inspired by MochiKit.
No offense to MochiKit or the Google JavaScript library but if past history is any indicator – developers are not clamoring for another MochiKit.
Open Web Tests
The final portion of this release is related to the programmatically-generated Open Web API reference. This is a full suite of tests that cover HTML elements, JavaScript/DOM methods, and CSS properties.
Thankfully raw dumps of the results are provided for each browser so we can use this as an opportunity to see what tests are being performed (and how the results compare).
Taking a look at the JavaScript/DOM results for Firefox 3 we see a lot of ‘existence’ tests. The vast majority of the tests appear to be checking to see if particular methods, or properties, exist. Scroll through we see some puzzling error messages:
3. document/document-attachEvent-typeof-test.html:testTypeOf failed
"[DocumentAttacheventMethod] typeOf(document.attachEvent) != 'undefined'"
Expected not to be <undefined> (String)
Firefox 3 is failing this test because it doesn’t have Internet Explorer’s proprietary attachEvent method? If you continue through the results you’ll see similar indicators all throughout. If you were to open Internet Explorer’s results you would see a number of fails for Netscape-specific methods/properties.
Opening up the HTML Firefox 3 results we see a similar situation. In this case the HTML tests appear to focus on the availability of attribute expandos on DOM elements. For example, here’s one failing test from Firefox 3:
293. attributes/ilayer-above-reflection-test.html:testReflection failed
"[IlayerAboveAttribute] ilayer.above reflects <ilayer above="foo">"
Expected <foo> (String) but was <undefined>
The ilayer element was a Netscape-specific HTML extension. Testing for its DOM compliance (and, by extension, its existence) seems quite futile.
If I had to guess as to how these tests were generated I’d say “open up a browser, spider every DOM property (or HTML attribute), and turn those into existence tests.”
This raises an important point: This suite is not built for any sort of standards compliance – at all – it’s simply designed to check for compatibility between browsers. Looking at this suite as a compatibility suite we can start to see some use – but it’s still terribly limited (only checking for existence is hardly a good-enough indicator of a browser’s proper support of a property or method).
If there’s one over-arching theme to the Google Doctype release it’s been “whatever we can generate automatically, or release with the least amount of fuss, let’s do that, no matter how simple it may be.” I’m definitely looking forward to when a full release comes along, but this doesn’t appear to be it.
Jason Wehmhoener (May 15, 2008 at 9:52 am)
I’m pretty skeptical that the “full release” is actually forthcoming. I think WYSIWYG, and they’re hoping we’re going to excitedly flesh it out by editing the wiki and submitting patches.
Eric Meyer (May 15, 2008 at 10:10 am)
I had similar thoughts, John– glad to know I’m not alone! As I tweeted, I thought it was particularly nice how they just barfed out every “CSS” property they had on hand, including gems like
acceleratorandime-mode, with no indication of their proprietary nature. Ditto for “HTML” elements, and I presume for the DOM as well.There’s promise there, I think, but right now it’s kind of undermining its own message of openness. I keep trying to imagine exactly how Mark Pilgrim would have acidly ripped at this had someone else done it this way, but I guess I’m just not that creative.
Chris Anderson (May 15, 2008 at 10:46 am)
I thought the goog.base.js (and its focus on namespacing and dependency management) was at least interesting, in a makes me want to work at Google less sort of way. I guess if you’ve got to have ceremony, its better than the YUI ceremony. It’s a wonder these big companies get anything done at all!
Marjolein Katsma (May 15, 2008 at 11:30 am)
The “Javascript-laden” version is not only that, but does not work at all (no article can be loaded) in Opera 9.2x, and I hear it’s crippled in IE7 (once an article is loaded you can’t load a new one). So much for Google’s addition to the “Open Web”. You won’t get there by ignoring open standards.
That said, I found the security section quite instructive, but the JavaScript section totally confusing – it seems there’s nothing there one can actually do anything with.
Erik Arvidsson (May 15, 2008 at 11:30 am)
The MDC articles are for Mozilla, just like MSDN is for IE.
I think we need something that covers the entire open web, not just a single company’s view of the web. I have very high hopes for DocType and I hope it will become a good resource for people interested in the open web. Yes, it needs more work but one person cannot document the whole open web by himself (except maybe PPK =P).
Chris: (I’m being defensive here) Gmail, Docs, Spreadsheets, Presentations, Picasa Web, Blogger, Sites and tons of other products have been using this JS for years. Do you still believe we don’t get anything done?
John Resig (May 15, 2008 at 11:44 am)
@Erik: That’s rather short-sighted, don’t you think? Considering that Mozilla is already documenting the ‘Open Web’ (if by ‘Open Web’ it means ‘Standards-compliant JavaScript, DOM, CSS, etc.’). In fact, the documentation is already 1) Much higher quality. 2) Includes examples and demos). 3) Specifies which browsers they work in.
For example, opening a page documenting document we can clearly see documentation for all of its properties and methods of that object (and which ones are Gecko-specific).
Additionally, comparing the Mozilla documentation (which is an open Wiki under a creative commons license) to MSDN (closed in every sense of the term) is incredibly disingenuous.
I can put forward that if it was proposed that the Mozilla DOM, CSS, JavaScript documentation only contain references to Open Web code that there would be little disagreement.
Eric Shepherd (May 15, 2008 at 11:47 am)
My goal with MDC is actually to provide complete documentation for the open web. Although as a matter of necessity our content is targeted at users of Mozilla software, anything that’s truly open should be documented on MDC.
Daniel (May 15, 2008 at 12:30 pm)
Object traversal, string manipulation, math helpers, and data structures are obscure? Blimey.
I don’t think they’re entering the popularity contest here.
But anyway, it’s nice that the reference links to sitepoint, msdn, and mozilla documentation. It’ll make for a good place to start. Which has also been done somewhere before.
Alex Rudnick (May 15, 2008 at 12:47 pm)
The dynamic version of the site is both linkable and bookmarkable :) That’s what’s going on with all of that “#p(doctype)s(doctype)t(Welcome)” stuff in your location bar.
Here’s a link, for example: http://code.google.com/docreader/#p(doctype)s(doctype)t(ArticleCoordinates)
Erik Arvidsson (May 15, 2008 at 12:51 pm)
I took a new look at MDC and it has improved a lot since we started Doctype. I’d like to apologize that I compared MDC to MSDN, that was uncalled for :-)
I have 2 example issues with MDC if it supposed to be useful for people writing applications for the open web.
1. Why is it exposing XPCOM internals like documentURIObject which even requires UniversalXPConnect priviledges? (document.documentURIObject) Are you repeating the issues that we saw with getBoxObjectFor by exposing XPCOM interfaces like these?
2. Why isn’t MDC documenting defacto standards like innerText and outerHTML that are available in all browsers but Firefox? The open web is more than just standards. For example VML is an important tool to allow IE to do vector graphics but documentation of that does not seem like it will ever appear on MDC.
Seriously, I like MDC but there needs to be a single place where people can go to get documentation about the open web. In a perfect world this would be MSDN + MDC + developer.apple.com + opera docs + PPK’s docs etc and personally I don’t care who is doing this as long as someone is doing it.
One more thing. I think there is a serious problem when people go to MSDN (which is still the best docs site out there) or MDC and blindly thinks that it will work. A documentation site needs to clearly document when something does not work in some browsers and it should also point to work arounds and/or alternatives for other browsers.
John Resig (May 15, 2008 at 12:57 pm)
@Daniel: Here’s a quick list of things that are more important than DOM traversal (apparently): Getting any property name from an object (goog.object.getAnyKey), truncating and adding … to the middle of a string (goog.string.truncateMiddle), converting degrees to radians (goog.math.toRadians), a queue data structure (goog.structs.Queue).
Popularity is a good indicator of one thing in the JavaScript world: a hard problem is being solved. Most modern JavaScript libraries tackle hard problems in an effective manner and so the users flock to them. DOM traversal is not an easy problem. Neither is Ajax. Constructing a queue, however? Very easy. I guess I was just expecting something a little more interesting from one of the foremost JavaScript-using companies.
@Alex: Note that I said easily – I think the broken URL in your comment is a pretty good indicator of the situation, unfortunately.
@Erik: I absolutely agree that MDC should encompass all browsers (and all aspects of the Open Web). Thankfully it’s just the sort of place where it can happen, as well (open, editable by all, clearly licensed). The reason why it isn’t there now isn’t out of spite, or competition, more just out of interest or effort.
Alex Graveley (May 15, 2008 at 1:42 pm)
DocType could quell a lot of these complaints by embedding the MDC and MSDN doco already out there on a given topic.
That would free the DocType wiki to become more about discussion of best practices with real-world examples, using a variety of JS libraries.
“On the ground” content like this will always feel out of place on a strictly documentation site. But its a resource that’s sorely lacking.
Sami Khan (May 15, 2008 at 2:52 pm)
Most of the stuff Google does in the open space is mostly thrown out there to get attention of developers and make them talk about it so they might come work at Google. Put another way it’s brand maintenance. I have yet to see (any) completed, useful open source output from Google that you can actually use to do any real work; correct me if I am wrong. The Google SOC is also another way to hire developers or maintain profiles so that they can find people to offer jobs to — it’s a recruiting tool. I see this as being no different. You guys put your lives into making useful stuff for the open space (Thanks Resig!), these guys only want to make money and hire more developers, they could care less about producing useful stuff for the open space. So in essence I think we should stop taking the bate, and just concentrate on our works. If they produce something worthy, then talk about it, otherwise might as well as ignore them.
Maciej Stachowiak (May 15, 2008 at 3:31 pm)
I thought the Google DocType docs were alarmingly low quality, I filed a few of the most obvious bugs here: http://code.google.com/p/doctype/issues/list , but this barely scratches the surface.
John, would MDC really be open to hosting documentation of browser-specific extensions for non-Mozilla browsers (or features that are part of standards that are not yet implemented by Mozilla)? I’d always assumed it would not, and I imagine most people who would consider contributing content have thought the same.
Eric Shepherd (May 15, 2008 at 4:07 pm)
Maciej —
Absolutely! MDC is intended to be documentation for the web, not just Firefox.
Daniel (May 15, 2008 at 4:29 pm)
@John, How many libraries are there that do DOM traversal? How many do we need?
John Resig (May 15, 2008 at 5:48 pm)
@Daniel: About the same number that do DOM manipulation, probably less. It’s weird that they would pick that problem but not traversal. Honestly I’d be more interested in seeing their Ajax library, which is bound to be considerable.
george (May 15, 2008 at 6:14 pm)
John you’re being a bit harsh :) It’s just a first release and you can see a lot of work there :) sure…it’s far from perfect or useful yet, but let’s wait to see the final product (if there is such thing :))
p.s. I’m not working for g. ;-)
DeWitt Clinton (May 15, 2008 at 6:29 pm)
One of the reasons Doctype is openly licensed (BSD and Creative Commons) is so that if people *want* to copy this into MDC (or wherever), they are more than welcome to.
As Erik said, the point of Doctype is to get the information out there in a free, open, and unbiased way. If MDC (or anywhere else) turns out to be a better place for this community to develop and the docs to live, then no one at Google is going to be upset. It just needs to happen somewhere.
-DeWitt
John Resig (May 15, 2008 at 7:11 pm)
@George: Yeah, I may be. I’ve got a cold and am being a little bit grumpy. Hope Google doesn’t take it too literally, just want to see good results.
@DeWitt: Thanks for stopping in! I’m real glad that it’s open. I definitely didn’t want to rain on the parade here – any attempts at bringing new browser documentation is hugely appreciated (especially by me). As I mentioned to George, I just want to push you guys hard to make sure you do your best.
DeWitt Clinton (May 15, 2008 at 7:20 pm)
@John — Please never stop pushing us. : )
Kit Sunde (May 15, 2008 at 8:03 pm)
I appreciate another source of information even though there’s not (yet) a lot besides tabular data, even if it ends up being used only as a reference for other places.
I don’t see how testing proprietary methods on all browsers is a bad thing considering where :hover, innerHTML, XMLHttpRequest and so on came from.
Robert Sayre (May 15, 2008 at 8:41 pm)
@DeWitt: is there a test suite for the google js library in the repository, so that it can be added to Mozilla’s post-checkin regression tests? We’ve caught regressions by including tests from jquery, prototype, etc.
Maciej Stachowiak (May 16, 2008 at 12:51 am)
@Eric Shepherd
If that’s the official policy it might be good to announce it. I was going to say if this was done I would encourage the WebKit community to document WebKit-specific extensions, but looking at the main page it looks *very* Mozilla-centric and I am not sure they would feel comfortable doing so.
http://developer.mozilla.org/en/docs/Main_Page
This includes the many uses of the Mozilla name, the Mozilla logo, a giant Firefox icon, a Firefox download link, and a bunch of links to Mozilla-specific topics (more than half the links on the page). Following a link to an area I know well, the DOM:
http://developer.mozilla.org/en/docs/DOM
This links to “Gecko DOM Reference”, “The Document Object Model in Mozilla”, and a bunch of other Mozilla-specific links. I don’t see any links referring to other browsers or indicating that any of the content applies to all browsers.
So if MDC is indeed meant to document the Web and not just Mozilla, then I don’t think it is doing a good job of conveying that message.
DeWitt Clinton (May 16, 2008 at 1:09 am)
@Rob – there may indeed be potential for automated regression tests here. Start poking around in http://code.google.com/p/doctype/source/browse/trunk/tests/ and let’s get Mark’s thoughts on this as well.
Mariusz Nowak (May 16, 2008 at 3:59 am)
I think Google was never after web standards (we can get it looking at their home page source code) which is sad I think. However they were always strong advocate for open web which is great.
..and this is what we got from them – great open web documentation with big dose of ignorance for web standards ;-)
Asbjørn Ulsberg (May 16, 2008 at 6:18 am)
I keep wondering why Google didn’t push this through as a test suite and documentation effort within W3C instead of pushing it as their own solution to everything. Right now, Doctype is way too half baked, proprietary and ambigous to be usable for anything (and don’t get me started on the hideous JavaScript “docreader”). There of course hope this will improve, but I’d much rather see the documentation of “The Open Web” on W3.org (where it belongs) than on Google.com.
Joshua E Cook (May 16, 2008 at 7:51 am)
John, w/r/t Alex’s comment about bookmarking and linking: the URI he presented was valid (parens are legal tokens within the URI fragment) and if there is a problem here, it’s with your commenting system not properly recognizing it. My browser has no problem with bookmarking that link from the address bar.
Si (May 16, 2008 at 10:49 am)
I think it’s really weird how there’s this big assumption in Mark’s video that “the community” is just going to come and fill out all the donkey work. Firstly, what community? You’ve got to build it. There isn’t some place on the internet where we all hangout together and chat shit (except reddit). Each site must build its OWN community. The conditions have to be right for creating a community too, having a place to be isn’t enough – just ask people in Flint.
Google seems to really suck at building communities. I think it’s because, deep down, if you got a Phd in CompSci, EE, maths or physics you’re probably not really all that sociable a person…
Still waiting to see what the “community” does with Google Doctype.
Robert Sayre (May 16, 2008 at 2:55 pm)
@DeWitt, yeah, I caught those. We already have bug 433809 open on it. I was hoping for a test directory under trunk/goog, which would be a slightly different thing.
zeldman (May 16, 2008 at 3:18 pm)
I had similar thoughts but you articulated them better than I could have. Thank you.
Garrett (May 16, 2008 at 6:20 pm)
@Erik:
Chris: (I’m being defensive here) Gmail, Docs, Spreadsheets, Presentations, Picasa Web, Blogger, Sites and tons of other products have been using this JS for years. Do you still believe we don’t get anything done?
Are these products are considered exemplary of Google’s quality standard? I think it’s time to have some code reviews on this.
What is the success of Google determined by? Is it directly attributed to the developers?
Mark (May 17, 2008 at 1:12 pm)
@Maciej: I remember when Safari first came out in beta. Were you around back then? It was pretty “low quality” too. It didn’t pass the CSS test suite because it couldn’t even LOAD the damn CSS test suite. (It gave an error “object of type text/html not supported” or something.) But there was Apple, putting this new browser out there for all the world to see. Why? Because shipping is a feature too.
I didn’t hold out a lot of hope for Safari back then, but y’all kept plugging away on it anyway. And 5 years later, Safari is the fastest browser in the world, and Webkit is the fastest rendering engine.
Maciej Stachowiak (May 17, 2008 at 6:08 pm)
@Mark: Yes, I was around when we released the first beta.
Safari was pretty fast then (faster than other Mac browsers of the time) and half-decent on compliance (we had a standalone copy of the CSS1 test suite that we did in fact pass if I recall correctly). It’s been a lot of work since then. But we also held off a long time on the first beta to try to get the basic quality level that people would be willing to try it, and added a lot of highly demanded features and fixes before we recommended general use.
I wish Google Doctype the best of luck. I even looked for issues and filed bugs! But I could not recommend it to anyone to use as a reference today. I hope that I can in the future.
Bernhard (May 26, 2008 at 11:01 am)
I wouldn’t recommend Google as a reference location for anything related to standards.
Take their Blogger blogging engine – the default templates are so faulty that any archived post triggers upwards of 300 validation errors in the W3C Validator.
Those who understand DTDs write clean websites – the others code for Google!
If you wanna read up on doctypes, read the W3C website. Straight from the horse’s mouth…