Slow start, great second half.
Stirring tribute to a hero.
Given our ongoing documentation-needed overload, we’ve decided to look into contracting out some writing work to help catch up our Firefox developer documentation. Basically, we’ve not been able to keep up with our Firefox X for developers documentation (see Firefox 17 for developers, for instance). While stuff gets listed, the list is often not complete, and even where items are put on the list, they’re usually not actually documented.
This is, frankly, embarrassing.
However, the staff writers, and even most of our community of writers, have been very busy with Firefox OS and other documentation, leaving Firefox itself rather strapped for attention. That’s got to change.
So the other day, I talked to Ali (my boss) and we agreed that we should see about contracting someone to go through all of these documents, from Firefox 13 onward, and get them fully up to date, and try to document the technologies and changes as needed.
There are some skills required:
- Likewise, you should be competent with HTML and CSS, at least well enough to sort things out without hand-holding.
- If you have experience reading the IDL that describes DOM interfaces, that’s a big help, but we can help you figure it out (it’s not hard).
- You should feel comfortable talking to developers by email and in IRC. You’ll have questions and being able to interface with these guys will be a huge help.
You won’t be in this alone, of course. Our existing community of writers hangs out in #devmo on irc.mozilla.org and we’ll be there to offer encouragement, advice, and some help.
If you’re interested, let me know. We haven’t opened up this contract yet, but I’d like to start getting a handle on who might be interested, so I can have a list of possible candidates ready to go once that happens.
This is important work that’s sadly fallen by the wayside due to limited resources and conflicting priorities. Help us make the Firefox developer documentation excellent again!
- The initial page moving feature has landed! It’s still very rough around the edges, and there are follow-up bugs to be addressed. Because of that, it’s disabled for everyone but administrators for now. But it’s getting there, and this is a big day we’ve been waiting for for a long time.
- The table in the revision dashboard has been reorganized a bit; the Comment column has been removed, and the comment is now displayed underneath the article’s title, when there’s a comment. In addition, the locale has been moved to the right side of the article title column.
- The Revision Diff section in the revision dashboard now shows the title of the article, so you have it handy down below if you’ve scrolled the list of articles off the screen.
- RSS feeds now default to 50 items being returned; you can change this by specifying a limit parameter in the request. We plan to add an offset parameter eventually as well, so you can get feed data in batches.
- We added support for CORS to the site that hosts sample code, to avoid errors that occurred when trying to load assets (such as fonts for @font-face).
- The datetime attribute has been white-listed, so it can be used.
- Updated the Persona authentication code.
This is a huge update! We attempted to land most of it on Friday but ran into a significant bug that required the update to be rolled back and repaired. That’s now done, and things look good. We hope to open page moving up more soon, once it’s had more testing. Stay tuned!
One of the relatively new features on MDN’s Kuma wiki — and one that’s still a work in progress — is the Revision Dashboard. This dashboard presents you with a list of the most recently changed articles, and lets you review those changes. Although the dashboard isn’t yet linked to from the UI on the MDN wiki, it’s there. We’ll add a link to it soon; we have some UI decisions to make first.
The dashboard page consists of three sections: the filter section, the revision list, and the revision diff.
At the top, there are filtering options.
You can choose to filter by locale, if you’re interested only in changes in a given locale. By default, you get all locales, but often you’re only interested in changes in your language (or in English if you’re looking for new stuff to translate). In addition, you can filter to find recent changes for a specific user. You can specify these filters in the URL, as well. For example:
The revision list is (surprisingly enough) a list of article revisions. Each row in the list corresponds to one edit to an article. The article’s locale and title are listed, as well as the date of the revision, the username of the person that made the change, and any comment they added when saving the article.
Clicking on a revision in the list displays the revision’s diff and additional options; with these, you can revert a change (thereby making the version of the article prior to the selected one current), view the page, open the page in the editor, or view the page’s complete history.
Clicking on an article’s title will open that article so you can read it in all its glory. Clicking a username filters the current list to only show changes made by that user.
After you’ve clicked on an article revision, the Revision Diff area shows a diff of the HTML, so you can see what changed in that revision of the article.
Viewing the actual article may be handy when reviewing more complex diffs, since it can be hard to gauge what exactly changed when looking at the raw HTML source.
The revision dashboard is undergoing ongoing development, so expect it to look different from time to time. In fact, I’m already seeing mockups of it looking rather different (and better!) than this in several ways. But the core functionality is there. Expect change, but it’ll be great change!
The “sample finder”
The biggest new feature is the addition of a new button has been added to the toolbar to let you insert an <iframe> for any code sample from anywhere on MDN. Simply click the button in the toolbar. This will present you with a dialog box like the following:
You can choose any section in the current document from which to pull sample code (which comes from the <pre> blocks inside that section). You can even choose to pull the sample from a different article entirely! This lets you reuse samples, share bits of code across pages, and so forth.
But wait, there’s more!
We have a few other updates, too!
- One of the fixes from earlier yesterday, to set minimum widths for columns in the revision dashboard, didn’t actually get picked up in the first push. It did, however, in the second.
- There have been more updates to the copy for the February Dev Derby.
- We reverted some of the changes to the Persona login, because the change to using the new API was not as simple has we’d been led to believe.
We continue to drive ever onward, forward, and upward!
- The HTML <time> element was being treated as a block element instead of as an inline element by the editor. This is now fixed.
- The page.subpages() KumaScript function now returns the subpage list sorted alphabetically.
- Columns in the revision dashboard have minimum widths now, to help prevent some awkward wrapping issues. It’s not perfect yet, but is much improved.
- The Persona authentication code has been updated to stop using some deprecated routines.
- Text describing prize information for the Dev Derby has been updated.
In other news (sort of), it turns out the revision dashboard was opened to the public a while back and nobody told me. I’ll be blogging about how to use it shortly!
The Mozilla Developer Network (MDN) is (and yeah, I may be a little biased here) one of the greatest online resources for Web developers you’ll find online. We’re constantly writing away, trying to make it better, and if you haven’t seen me (or one of our other team members) out there trolling for more people to write documentation, you’ve probably not been paying attention. Which is fine — because maybe you’re not much of a writer, or you prefer to hammer away at code.
Make the documentation platform better
MDN uses our very own, open-source, Kuma wiki platform to power its documentation. We’re hard at work to make the software better, with our fabulous and hard-working development team pounding out code at ludicrous speed.
That said, however, there are plenty of things on our development team’s to-do list, and some help is always welcome. In addition, maybe you have an idea of your own!
The Kuma code is available on Github. Feel free to pull it and see what you can do. There are instructions available for how to set up your build environment, as well as for how to contribute to the code.
If you’d like to talk with the development team, get help, and even talk with the writers that are most engaged with the development process, feel free to pop into the #mdndev channel on IRC. You can also keep an eye on what the rest of the development team is up to by checking out their status updates on our Standu.ps site.
A key feature of any developer documentation is good sample code. While we have some sample code, we can always use more. Until recently, adding samples was not always easy, especially if you wanted people to actually be able to see what the code does. However, with the recent addition of our live inline sample support, that’s all changed for the better.
Examples don’t have to be fancy or flashy. Indeed, the simpler they are, the better, in most cases. The less extra “stuff” there is for the reader to have to deal with, the more quickly they can get to the heart of the matter and really understand what they’re looking at.
Help me, Coder-wan Kenobi… you’re my only hope
There’s a ton to do! Between documentation (that’s where the writing community comes in), the Kuma project (where our Kuma dev team, hopefully including you soon, comes in), and samples (where, well, everyone comes in!), there’s plenty to be done. There’s something out there for everyone. Can you find your perfect place to contribute to help make the best online resource for Web developers even better?