In case you have not heard, one of the very important new Mozilla initiatives is the documentation project called the “Mozilla Developer Center”, or “devmo” for short. Mozilla has already proved successful at open software development and open community-based marketing, and this is the next logical step: an open, community-based documentation resource for web developers, extension authors, XUL application developers, and core Mozilla developers.<\/p>\n
This documentation effort is in full swing right now; visit http:\/\/developer-test.mozilla.org\/ to see it in action. It is powered by MediaWiki<\/a>, a powerful and extensible piece of server software that allows for community collaboration in editing documents. Mediawiki has a long track record as the software that powers Wikipedia<\/a>, the free encyclopedia.<\/p>\n I am personally very excited by the energy I already see in the devmo project, and it’s explosive potential when it is actually “launched”. One of the historical weaknesses in Mozilla as a development platform is the lack of good documentation, and devmo is taking up the challenge in a big way. Devmo is under the experienced leadership of Deb Richards<\/a>, who I have gotten to know over the past few months as person who can keep an vast number of things going and not lose sight of the final goal.<\/p>\n Which is why I am writing this post not to rain on the parade, but to discuss the challenges that I see facing the project. Most importantly, how devmo presents dense reference material is going to be critically important to its most important “consumer”, web developers and XUL application authors. The wikitext format lends itself quite readily to tutorials and articles, and I am working at making code samples work without a lot of pain. But reference material is not easy to either write or present in traditional wiki format. For a point of reference, please visit the msdn.microsoft.com page about the html <applet> tag<\/a>. To understand what I really want out of devmo, visit that page in IE.<\/p>\n The property list is presented as a dense and highly-hyperlinked table. But the most important part of that table is that it is absolutely complete. You don’t have to go visit “the properties of DOM Objects” and “the properties of HTML Objects” to see what is available on this DOM element. But I want more! I want to be able to say “show me which properties were available in mozilla 1.x”.<\/p>\n When the gecko developers add a new method to a DOM object, it is unlikely that anyone is going to systematically go through and add this property to every one of several hundred individual element pages with the correct descriptive text and versioning information. Reference material is a recipe for out-of-date or incomplete documentation; documentation which does not list the minimum runtime for which a particlar method\/property\/style became available is almost worse than useless.<\/p>\n I believe that creating this kind of dense documentation is going to require that these cross-references are created in some kind of XML syntax. I believe that this XML should live in a wiki “page” so that it can be edited by the community like any other page. The advanced sorting capabilities that you see on the IE version can be provided through the use of XBL bindings in such a way that clients which do not support XBL will get the full property table (there are other possible solutions involving cross-browser scripting which would be more complicated but would be compatible with more browsers).<\/p>\n Finally, one of the major features that I want out of devmo is to provide context-sensitive help in rich-client editing tools. Everything from the XUL Application Creator slated to be part of the XULRunner Developer Kit to NVU could really use context-sensitive help when editing markup of various kinds including HTML\/XHTML\/XUL\/CSS\/JS. For this to be practical, large parts of the metadata provided by devmo will need to be in machine-readable formats.<\/p>\n