developer.mozilla.org
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.
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 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, the free encyclopedia.
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, 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.
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. To understand what I really want out of devmo, visit that page in IE.
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”.
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.
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).
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.
I know that I am asking a lot out of devmo. It’s not going to get there overnight, and that should not stop anyone from contributing an article or helping edit right now. I especially encourage people with editing skills to get involved and clean up the articles that people like me might write.
July 13th, 2005 at 11:02 pm
This could be done by transclusion: that is, by using MediaWiki’s template feature. The downside would be that using templates too frequently might slow down the servers, which often happens at Wikipedia due to overuse of so-called “meta-templates.”
July 13th, 2005 at 11:39 pm
Dear sir,
I have become critical of the developer.mozilla.org documentation project.
1- Anyone can modify any current document for any reason, without even explaining changes. If you think this is a good thing, then I definately disagree with you.
2- No interactive js-driven demo/example possible. At least, it certainly is not straightforward to embed, include an interactive demo in a wiki page. Consider what I have been able to do at Gecko DOM reference in these 2 files:
http://www.mozilla.org/docs/dom/domref/scrollTop.html
http://www.mozilla.org/docs/dom/domref/dom_window_ref28.html
I can not do the same at developer-test.mozilla.org. And even if I could do it, then point 1 pops up: anyone can undo at anytime what I could do for any reason.
3- Many articles are without any working examples, interactive demos, good document structure, are not oriented toward the ordinary web author wishing to upgrade his webpage to support Mozilla products. Frankly, this is where mozilla.org should improve: make good, working, compliant, interactive, useful, meaningful documentation pages for ordinary web authors wishing to support mozilla products, wishing to make their page work without a problem with Firefox, Mozilla Suite, Camino, etc,etc.etc
You can not expect tons of text and tons of reading to interest readers and achieve results (converting readers to support in reality mozilla in their website). If the ordinary web author could speak up, I bet he would say at the middle of an article: “Stop writing! Gimme something to view, show me a picture, an image summing up your concept, an interactive example to look at, to play with.”
4- IMHO, a few articles coming/migrated from devedge are simply outdated, sometimes quite wrong. They are litterally “pasted” into an empty blank page and then the date at developer.mozilla.org changes: I think that’s wrong.
5- XHTML based. Why it was needed to be XHTML 1.0 transitional is beyond me. If the whole mozilla.org site is in the ongoing/continuous process of migrating/converting to strict HTML 4.01, then why is it that we should have it XHTML transitional here. I don’t get it. We say/have said “A” and we do “B”.
6- Lots of HTML tags, HTML elements and attributes do not work, are not usable at developer.mozilla.org. I listed several of them here:
http://developer-test.mozilla.org/en/docs/Help_talk:Wiki_Markup_Reference
Finally, I want to underline that Deb Richards has done a terrific and colossal work at developer.mozilla.org. My comments are not suggesting implicitly nor explicitly that she is responsible for the flaws, difficulties or problems I see at developer.mozilla.org.
Gérard Talbot
July 14th, 2005 at 11:36 am
I was originally very concerned about the concept of anyone being able to edit devmo as a wiki. Deb has convinced me otherwise in the past few months: we must reduce the documentation barriers to entry as much as possible, and devmo must thrive as an open community process. Sure, we’re going to have situations where people make inappropriate changes, but that’s what we have editors and page history for, and in cases of persistent wrongdoing we can disable the offender’s account. There may be a future where certain kinds of documentation changes are subject to a review process (anyone can make a change, but those changes will be moderated). But that is IMO in the “advanced management” category, not anywhere near a top priority.
Being able to provide working examples are a top priority, and the infrastructure bug to allow them is filed, see https://bugzilla.mozilla.org/show_bug.cgi?id=300657
The issues with the actual content in #3 and #4 are easily dealth with by updating or removing obsolete documents. The more people we have involved, the easier that is. Please feel free to mark documents that appear out of date in the appropriate needs-work or needs-editing categories.
The other issues I don’t know anything about ;-)
July 14th, 2005 at 8:21 pm
“we must reduce the documentation barriers to entry as much as possible, and devmo must thrive as an open community process. Sure, we’re going to have situations where people make inappropriate changes, but that’s what we have editors and page history for, and in cases of persistent wrongdoing we can disable the offender’s account”
First off, I don’t understand why you say “we have editors” or what you mean with “we have editors”.
I do not agree with what you say. I’m not talking in an abstract manner, not in an hypothetical manner, nor in a theoretical manner but I’m speaking out my opinion after getting involved in updating files and spending a lot of time doing so. Anyone can make any change for any reason without justifying or explaining himself. Therefore, the discussion page is *absolutely* optional: that’s a fact.
There are lots of ways of sabotaging and undermining an article. You can just snip a sentence here, change a few words over there, nitpick as much as you want, reformulate a paragraph there, and then add a comment saying “what you say is bogus”, “it’s not clear”, “that part was nonsense”, “that’s silly argument you had”, etc.. To sabotage the efforts of others, you don’t have to be outright agressive and hostile. You just have to later say, claim that you were merely “updating” someone else’s article for the better.
Original authors of articles have zero power over modifications: original authors don’t exist anymore with such freedom granted to anyone at developer.mozilla.org.
There is and there will be a price for lifting up any/all barriers to technical documentation that, so far, not a lot of people have really measured.
Bring 10 randomly chosen web authors together in an internet chat room, give them all they need to write a book (time and resources) and allow each one of them to modify the text of others, and I assure you they will not be able to get along and agree on the writing of a 100 pages book on web authoring.
The goal (the dream) of developer.mozilla.org was to let web authors and knowledgeable people be able to update articles of anyone else in any way, manner they want: I think this is where I see problems. The site vandals won’t be the problem.
You have not answered me on the interactive example issue. If nothing is done in that area, then documentation at developer.mozilla.org will become a huge mass of text-based inter-linked articles, some sort of opened+links books litterally without interactive examples. Popular tutorial sites which demonstrate/teach javascript, DOM and DHTML features (and other web programming languages) have interactive examples. People can forget a 20Kb long article but they will usually remember a good interactive example much better, much easier.
Gérard Talbot
July 15th, 2005 at 4:45 am
Gérard: All the points that you make about wikis apply equally to wikipedia, kb.mozillazine.org and many others. Yet those sites don’t seem to be undermined by arguments between the (hundreds of) authors. Your concern seems to be that you won’t be able to exert full artistic control over something that you write. But that’s probably a good thing for the users of the documentation – people get very attached to things they write to the extent that they miss obvious ways of improving their clarity and so on. And if somebody changes an article in a way that you dislike – well that’s why wikis come with excellent history implementations.
The current problem with Mozilla documentation is that it doesn’t exist (compared with, say, Qt). Anything that causes more documentation to exist is good for users even if it’s imperfect.
July 15th, 2005 at 6:47 am
“Your concern seems to be that you won’t be able to exert full artistic control over something that you write.”
My concern is that anything can happen to an article and there is no rules, no policy, no borderline I see in making changes. Some sort of “free-for-all” without responsibility, accountability, imputability.
“But that’s probably a good thing for the users of the documentation – people get very attached to things they write to the extent that they miss obvious ways of improving their clarity and so on.”
Reviewing and proposing changes about an article is one thing. Rude manners, tactless/abrasive remarks (when commenting, making your own changes on top of that) and obvious nitpicking are quite different things.
Outright off topic comments, profanity, spamming, personal attacks, etc… any kind of outright wrong doing won’t be a problem at developer.mozilla.org. That’s not my concern.
E.g., what’s preventing “Joe Smuck” from entering a document about CSS at developer.mozilla.org and add comments like
“CSS is not that well supported”,
“current CSS implementations are buggy in Mozilla products”,
“CSS is even buggier in MSIE 5+”,
“CSS has limitations after all”,
“CSS is still at level 1: after 8 years of waiting, the W3C still has not fix its own incoherences and flaws in its level 2 spec”,
“Table-design is often a better choice than CSS and offers consistent look across all browsers”,
“Table-design is easier to do, easier to maintain”,
“frames is both backward and forward-compatible; CSS won’t work in all browsers”, etc..
Some parts of these statements are quite true, you know (the context in which they may be said is very important too). Now, if “Joe Smuck” adds these statements in any article trying to explain and promote adoption of CSS over old, deprecated coding techniques, then I assure you that “Joe Smuck” will irritate the original author. One can disrupt and undermine the whole work and perspective behind an article by these sorts of comments; one can disrupt the internal coherence and perspective of an article (originally written by 1 single person) in all kinds of ways.
I have listened to proposals whenever I was assigned to documentation bugfiles at bugzilla and above 90% of all submitted proposals I received were endorsed, adopted by me. I claim I had the same open-mindedness with an article I wrote and submitted to developer.mozilla.org. I made some proposals too in documentation bugs at bugzilla which were not assigned to me: some were adopted, others were not. I accepted that.
“if somebody changes an article in a way that you dislike – well that’s why wikis come with excellent history implementations.”
There must be some kind of misunderstanding somewhere. To me, these wiki-based documentation are like an endless ping-pong game perpetually going on where anyone/everyone has a racquet. So change whatever you want, tomorrow someone can change it back or add things which may contradict what was there and all of this is absolutely ok according to wiki-“playing rules”.
As the original author of an article, I have no control over what anyone can change in an article even without explaining himself on top of all that. Making changes, even minor ones, can be irritating. Making changes and then adding comments is quite different from proposing changes.
I understand the spirit which motivated the decision to go with wikimedia: open up the doors and more people will get involved and fill in gaps, holes. But then, you should expect problems to appear eventually. Freedom, liberty without controls, rules or any kind of sensible regulation mechanism is a guarantee of abuse and a promise of self-destruction in any social organization.
“Anything that causes more documentation to exist is good for users even if it’s imperfect.”
Sorry but I can’t agree with this. You seem to imply that anyone can write good, useful
documentation. Your statement may understandably wish to favor people to write documentation but the reality is that not anyone/everyone can write useful, meaningful documentation. We don’t all have the same level of expertise in web programming languages. “Joe Smuck” shouldn’t be able to edit anything he wants in serious documentation project.
Gérard Talbot
July 15th, 2005 at 10:30 am
(isn’t dria called Deb Richardson, not Richards?)
I fully agree with you that devmo needs references in such a form. Using cross-browser techniques for that is probably better, so that people can use any browser they want when finding out what gecko supports.
Of course such references may be somewhat redundant with W3C specifications..
July 15th, 2005 at 12:50 pm
“E.g., what’s preventing “Joe Smuckâ€? from entering a document about CSS at developer.mozilla.org and add comments like [snip]”:
Nothing. But in practice that doesn’t seem to be a problem. If it does become a problem on certian pages they can be locked and people can go file bugs for modifications in the traditional way. This, of course, has all the disadvantages of the current system (documentation owners leave, files get out of date, patches rot unchecked-in until they too are out of date, and so on). Indeed this course was taken with the mozillazine feature comparision charts ( http://kb.mozillazine.org/Intro_:_Comparison ) which, as a consequence are out of date (note in this case abuse was not the problem, rather too many people were editing the charts and neglecting the other content).
“So change whatever you want, tomorrow someone can change it back or add things which may contradict what was there and all of this is absolutely ok according to wiki-â€?playing rulesâ€?.”
Yes, sort of. However there’s substantial real-world evidence that wikis work. That’s probably because, in general, the set of people who benefit from disrupting the wiki is much smaller than the set of people who stand to gain by improving it. So, over time, useful content stays and useless content is removed.
It seems to me that you’re assuming the existence of a problem, pointing out that wikis don’t solve that problem and then concluding that they’re not good for “serious” projects. Yet there’s a wealth of evidence that the problem just isn’t there or, at least, isn’t as big as you make out. On the other hand, there’s lots of evidence that the bugzilla-based documentation system doesn’t work. So you seem to be objecting to transitioning away from a system that doesn’t work to one that is proven to work because of a problem that doesn’t exist. That doesn’t make sense to me.
“the reality is that not anyone/everyone can write useful, meaningful documentation”
Maybe. But every piece of documentation in a wiki-based system represents something that someone feels ought to be documented. If you find a piece of documentation that you don’t like, it’s much easier to make incremental improvements to that piece of documentation than it is to find the motivation to start an entirely new document. Seeing an inaccurate documenet is likely to make someone who has not yet contributed make a few small fixes and, perhaps, go on to become a regular contributer. That’s how documentation communities build up and even inaccurate, but well-meaning, contributions can be important.
For the record, I agree with some of the technical concerns – hopefully these will be addressed soon. But if you want to understand why the Wiki is going to produce much better Mozilla documentation than the old system, you have to stop thinking of documentation as being fundamentally single-author works with well-defined owners and look at them more as works by and for a large group of interested parties all of whom mutually benefit by ensuing that the quality of the documents in the system is high.
July 15th, 2005 at 9:58 pm
“(…) ‘tomorrow someone can change it back or add things which may contradict what was there and all of this is absolutely ok according to wiki-â€?playing rulesâ€?’. Yes, sort of.”
It is not “sort of”. It is not maybe or perhaps or anything like that. Anyone can change, add or remove anything at anytime for any reason and without even explaining why: that is the rule of wiki, that is a fact, not an opinion. There is no relativity in there. No review board, no need to explain first, no need to say anything at all even after changing whatever you’ve changed.
“It seems to me that you’re assuming the existence of a problem, pointing out that wikis don’t solve that problem and then concluding that they’re not good for “seriousâ€? projects. Yet there’s a wealth of evidence that the problem just isn’t there or, at least, isn’t as big as you make out.”
The conclusions I reached are based on personal time invested, after being involved. The conclusions I reached are not based on a general perception, not based on a survey, or what wikis do/achieve elsewhere. I see flaws, problems with the wiki system.
“there’s lots of evidence that the bugzilla-based documentation system doesn’t work.”
Personally, I have made every documentation bugfile in which I was assigned work and achieve its goals. Bugzilla-based documentation system had problems and limitations just like wiki-based one has.
“So you seem to be objecting to transitioning away from a system that doesn’t work to one that is proven to work because of a problem that doesn’t exist. That doesn’t make sense to me.”
I pointed out real problems or weaknesses after getting involved: I listed 6 of them in my initial post in the most objective manner I could present these. I know I’m not going to revert any transition now. I was not posting these posts with the expectation to change anything with my posts. I know I’ve spoken about these issues and these problems in a sincere manner and in a truthful manner. I have not imagine problems that do not exist on wiki.
Single-author documents have other benefits (or characteristics if you prefer) over community/multiple-parties involved documentation. Single-author documents will have generally a better orientation, a more consistent internal coherence, the author has to plan the document scope, audience, goals, what to explain, delimit certain areas, which examples to provide, what he wants to address, to focus on, etc…; the author will speak from and thanks to his own unique experience.
In a multiple author writing mode, documents will not have necessarly an overall consequent orientation (it may lead to contradictions in the document itself), it will be driven by the various (and possibly contradictory) perspectives from people with different web authoring experience. A multiple-parties document does not have predefined limits, pre-established scope, pre-agreed plan of any sort; wiki documents involve people who don’t even know each other, who don’t necessarly agree to begin with on lots of non-discussed issues. I really think what I said about 10 web authors not knowing each other and locked in a chat room: they would not be able to write a 100 pages book on web authoring without interfering with others’ writings. 10 different web authors have 10 different web authoring experience and 10 depths of experience of web authoring. Web authoring is not an exact “science” without debate, without discussion, without perspectives, without practical experience. Web authoring is often not a team project, not a team perspective, not a team experience.
January 11th, 2007 at 11:42 am
[…] Single-author documents will have generally a better orientation, […]
I don’t think so. Single-author documents will always be tainted one way or another by the author’s beliefs and preferences. In the case of a wiki, if someone thinks that the current redaction doesn’t exhibit a “neutral point of view” (NPOV) standpoint, he makes some changes to bring it nearer to what he believes is “neutral”. For controversial subjects, this can degenerate into a ping-pong game between authors with opposite opinions, but this is where a moderator, or even a moderating robot, steps in by locking any pages where edit reversals exceed a certain threshold frequency. Then discussion starts on the talk pages, where arguments pro and con can be exchanged, until a consensus is reached — or not. If no consensus is reached, the POV banner stays on the page, warning readers that the text might be biased. But in general, and considering the fact that “serious” users (who want to arrive at an objective and true-to-fact content) outnumber the trolls by several orders of magnitude, the result will approach the goal, even though — like any human endeavour — it will never be perfect.
This can be seen in the frame of the larger picture: a wiki is “open-source” documentation, like some well-known and hugely successful programs and systems are “open-source software”. IMHO we see here one more example of the superiority of the Bazaar model over the Cathedral model, whose central authority and strict padlocks restrict the number of hands which can work on the projects, and ultimately cause the cathedral to topple over by catching its feet in the carpet of its own restrictions (if you don’t mind my mixed metaphors).