------------------
Gecko DOM reference problems and suggestions
Over the last 2 weeks, I've checked the Gecko DOM reference (GDR) from many angles. Here's a limited list of the problems I see.
Content -------
The list of properties, methods is incomplete.
The vocabulary used in many details page is loose, misleading, confusing at times. Sometimes, definitions given are simply wrong.
Most of the detail pages do not have any example. Those who have an example section just include an excerpt of code which cannot be viewed, tried interactively on the page: so its instructional value is very limited and questionable. Even many examples in detail pages with excerpts of code serving as examples do not work, can not be working since there are several blatant syntax errors in it.
Incomplete list of properties and incomplete list of methods. E.g.: clientLeft, client, client, client, offset, offset, offset, offset, scroll, scroll, scroll, scroll,document.body.client/offset/scroll*, document.documentElement.client/offset/scroll*. Some definitions in the summary page are not the same as the ones in detail pages.
MSDN does a lot better here. Irt.org does better as well. Zvon.org, webreference.com, webreview.com,etc do a lot better. I believe mozilla.org ought to ambition, to look for a higher level of quality. That does not mean to release the equivalent of a whole book every week. Display:block and display:none are fairly well supported in a majority of currently used browsers, you know: isn't it what MSDN use in their reference docs? Popups don't always mean banner ads either: popups in a reference files might be mighty relevant, useful.
Being valid and consequent --------------------------
Many (if not all!) summary pages and detail pages have hundreds of validation errors: that's right! Hundreds of validating errors!
For instance,
http://www.mozilla.org/docs/dom/domref/dom_event_ref.html#998197
which is the event interface page has 113 validation errors according to xhtml1 transitional DTD. Now, this page didn't even have a valid doctype declaration on top of all that; so I had to edit the doctype declaration myself before validating it with the W3C validation service. This is really embarassing. In hundreds of ways, it tells the user: "We preach theory and/or coding manners which we don't apply to ourselves: so, just learn from the theory and manners we deny in pratice to ourselves. We teach and 'evangelize' what we refuse to ourselves." Mozilla.org has tried to be the champion of web standards over the last few years... and it nevertheless fails to validate by a large margin.
Usefulness, relevance ---------------------
80% of the time, the "Notes and Specification" sections are minimal, abstract, with general useless info, are often empty, without any relevant comment regarding compatibility.
The "Specification" section are empty or leading to a W3C spec/recommandation document. Compatibility with other browsers is not defined anywhere. Mozilla versions at which a property or method was implemented is not defined anywhere. Exceptions or details regarding the use of the property or method are pretty well absent. I really question the usefulness of the current content of these sections: with proper content, such sections would be useful and relevant. I'm not trying to condemn the efforts of others behind these files: I'm merely pointing out a problem, an emptyness here.
Vocabulary ----------
Loose use of words: Parameters is a word used in each and all detail pages, even in property pages. Does that make sense? x = y. And now x is a parameter!
Inconsistent use of identifiers, use of identifiers leading to confusing. Event is an object: the example nevertheless uses the e object. Now, for people learning a new language, another, separate DOM, the whole thing is rather chaotic, undifferentiated and misleading.
Here's an example: [ Syntax
targ = event.target
Parameters
targ is a reference to an EventTarget. Example
d = document.getElementById("d1");
if e.target != d
resetGame(); // not my event!
]The docs have no lexical glossary of expressions used. How many of you can define and untangle without a problem the meaning of client area, content area, viewing area, rendering area, document view, document offset, window inner dimensions, viewport, canvas, scrolling area? This is where documentation, reference might do a difference, you know... by using a proper vocubulary. This is where *A* reference document ought to teach, show, give the example and contribute to a higher level of better code practice by being irreproachable from the vocabulary perspective to begin with.
I see a lot of other areas where GDR is inconsequent, obviously incoherent, toughtlessly counter-productive, inaccessible, counter-usable, invisible, neurologically silent,etc.
Still after more than 6 days, some of the corrections, updates, clarifications I forwarded in a bug file (after careful examination and editing) - and in private emails as well - are still not uploaded. There are problems which are above people (and number of people) involved:
- better tools (for editing, uploading, html layout, formating structures, templates, etc.),
- standardized format,
- communication cycles,
- understood and well-known standardized protocols for multi-lateral contributions in an open source project aiming at sanitizing GDR.
I have seen no public discussion on how to avoid wasted redundant volunteer efforts, how to avoid volunteer efforts spent into a project (like GDR) which will have to be undone later and then redone, reformated, re-structured all over again later,etc.
I wonder why efforts in that field have to be done without any inter-partnership with other organization. If the task of creating, updating, continuously tuning/updating a reference documentation is so colossal, overwhelming, then I don't understand why such reference should not be the fruit of a partnership with some other official body. Aren't we after all duplicating the efforts of B. Clary at DevEdge in some way?
It seems to me that mozilla.org is like a factory where bugs are filed, discussed, examined and squashed, where new features are implemented but only later, much later documented, new specs, recommandations are implemented (with more or less reasonable success) but are not documented, where the whole site seems difficult to navigate, search and figure out. The thing is that when I'm looking for a particular information, I can use, figure out, navigate a lot better other sites which are vast and heavy but I never am able to achieve the same with mozilla.org even after months of usage.
I wonder how GDR can really achieve the purposes it's supposed to serve if content, coding pratices, manners, structures and working order, etc.. are wrong, misleading, poorly worded, contradictory, counter-productive. References should be auto-logical, auto-consequent and auto-productive in all kinds of perspectives. They ought to aim at elevating the user's coding practice, theoretical knowledge, understanding and at respecting and encourageing the efforts, the input of volunteers.
(...)
DU -- Javascript and Browser bugs: http://www10.brinkster.com/doctorunclear/
