Note: This blog post started as a rant about MDN which is sadly not very useful for add-on authors way too often. I tried to reformulate it in a neutral way. The point definitely isn’t blaming the people working hard on keeping that documentation up to date.
MDN has some great content. However, as far as extension development goes, maybe somewhat less content and more structure/quality would be beneficial. Yes, there are a few well-written overview articles. But quite frankly, I’ve seen them for the first time today — because most of the time I’ll get to MDN via a search engine. And if you take this route, there is a good chance to hit an article that pre-dates Firefox 4.0.
Don’t believe me? Try searching for a guide to write XPCOM components. You are bound to hit this book written more than a decade ago. Not only is it horribly outdated, it explains how one would create such a component in C++ — something that is completely impracticable for extensions in current Firefox versions.
The next search hit is only marginally better. The examples here have been somewhat updated to work in recent Firefox versions. It starts by sending people to an extension which is compatible with Firefox 3.0. It then explains the scary details of defining your own interface — yet most developers simply want to implement an existing interface. And as if the original document wasn’t already crappy enough, somebody also added instructions on integrating the whole thing into the Mozilla build system — all that before the actually relevant stuff of course. You might also end up in this troubleshooting guide which used to be pretty helpful — five years ago.
In fact, XPCOM Changes in Gecko 2.0 seems to be the only piece of documentation with a complete explanation, starting with the code of the component itself and ending with the way it is registered via chrome.manifest. Not that this document is comprehensible, being primarily a list of changes. And of course, that’s a place where nobody will come looking.
Another example: JavaScript Debugger API. The old API (ugly but well-documented) has been removed from Firefox, taking a look at the new one is overdue. There is an easy to find JS Debugger API Guide, linking to a seemingly complete JS Debugger API Reference. Great, right? But it is incomplete and outdated. In particular, the most important piece of information for extensions is missing: how do I find the existing global objects?
And then there is a document called Debugger-API, confusingly placed under Firefox Developer Tools. It took a while for me to realize that it isn’t related to the debugger tool in Firefox, it’s rather an autogenerated documentation of the JavaScript Debugger API. And this one seems to be complete and current! “Autogenerated” here means that somebody from the SpiderMonkey team didn’t want to mess with the wiki syntax (cannot blame them) and put a bunch of Markdown files into the SpiderMonkey source tree instead — these were then imported into MDN.
This isn’t even about the long list of nice functionality that was implemented but never documented. Like the XPCOM iterator helpers introduced four years ago. Or a way to listen to all events. Or a way to apply user stylesheets to individual documents. Yes, the dev-doc-needed queue is very long and there is only so many people who contribute to MDN (besides, they would also need to understand the change).
So, how can this be solved? I see a few options:
- Marking documents as deprecated or obsolete isn’t sufficient, documents that aren’t useful need huge and very visible warnings at the very least. But frankly, why still keep them around?
- Mozilla has great technical writers but they clearly cannot keep up. That’s not really surprising given how much Mozilla has grown. Maybe developers who actually wrote the changes could help beyond setting the
dev-doc-neededflag? Sure, not everybody is a great writer. However, some documentation is already something that can be improved. - Some documents like the ones on XPCOM components and JavaScript modules can be checked automatically — a script can verify that the documented interface matches the current source code. If they don’t they can be flagged as needing an update (maybe even visible to MDN users and editors).
Anything else that can be done?
Comments
Well, it’s definitely not a problem that’s unique to MDN… the internet is full of misleadingly-obsolete information, technical recommendations that were good practice in 2004 but ten years later, are dangerously bad ideas. And it’s really not much better in the commercial closed-source world… the company I work for has tons of documentation on different processes and components of our product – but because nobody really owns all that documentation, it tends to be poorly maintained… one of the experts might fix it up if they find something wrong, but they don’t really have time to do anything systematic.
The best I can offer is that it has to be dealt with as part of the development process. Preferably, that means that the developer takes responsibility for actually fixing documentation that’s obsoleted by their changes – but failing that, the developer should at least have some mechanism (and responsibility) for finding and flagging documentation that needs reviewing or rework, and some way to find such documents… treat it the same way you would treat a functional bug.
Remove all topics from MDN that should be covered by docs.webplatform.org .
Write less on MDN. That is, many pages that should contain reference information have been drowned in prose and wiki-layout making them slow to use. As opposed to e.g. w3school (which some Mozillians love to hate) that give the needed info upfront (and load over 4 times faster — in a test I just ran with webpagetest.org) or caniuse.com .
What does docs.webplatform.org have to do with Firefox add-ons?
My reasoning was, that if you remove stuff from MDN that is better handled elsewhere, it leaves more resources for the Mozilla specific stuff.
So… there’s a lot right here. Unfortunately, the small MDN team can only do so much, and given that open Web developers vastly outnumber add-on developers, and the current emphasis on apps and Firefox OS, most of our time goes there, and the XPCOM and other add-on related content has fallen badly out of date.
We are working on an answer for this problem, but it’s probably not going to involve the docs suddenly becoming up-to-date. We’re likely to have to rely heavily on the engineering teams and community members to do much of this work. Ideally, we’d come up with plans and guidelines, and then set people to it, but the details have to be hashed out, and we’ll need input from engineers and add-on developers to make even a plan happen.
When we’re ready to make a move on this, we’ll post to the relevant lists. For now, we do have some minor work being done to address a couple of specific problems that have been recognized as pain points, but this is a very limited effort.
I’m very much an “if it’s not all fully documented, the docs aren’t right” kind of guy, so having this stuff in this condition is a gnawing pain for me. I’m eager to find an answer. We’ll keep you posted.
Eric, let me take this opportunity to thank you for your great work. I’m certainly not expecting things to improve overnight – it took a while for the documentation to get into the current bad shape, it will take a while to get out of it again. MDN content is just too massive for anything to happen quickly. All I can hope for is a plan. So I’m eagerly awaiting your announcements.
> Maybe developers who actually wrote the changes could help beyond setting the dev-doc-needed flag?
It seems developers don’t even care about adding the dev-doc-needed flag… See Components.utils idl for example.