Jul 312009

I’ve been continuing to do back-end work on the Mozilla Developer Center this week, and have achieved a few things, some of which are already visible, and others that will be once IT has a chance to deploy some changes.

First, and simplest, I fixed the Interface template to stop inserting an extraneous space after the interface name; this will make several spots in our text look less… odd.

I’ve configured the syntax highlighter extension so it only offers options for languages we actually use, instead of including stuff like Delphi, for example. The “graphviz” options listed at the beginning… I’m not sure why they’re still there; I’m looking into it.

I’ve also written a new special page plugin that most of you will never directly see, but will let me easily do mass renames of tags, so that, for example, I can change “Developing_Mozilla” to “Developing Mozilla”. It will also let me fix various organization problems centered around tags quite easily.  This needs to be installed by IT, but it’s in SVN now, ready for them to grab it.

Then I updated the skin slightly, so that on search result pages, talk pages are actually labeled as talk pages now. This should help a little bit when trying to track down the content you’re really looking for.

In addition, sent along information to IT about how to configure MindTouch 2009 to support using SSL only on specified pages, instead of sitewide. If/when they choose to implement that, it should improve performance in typical usage.

There’s more in work, and of course I’ll blog more as I make further progress.

 Posted by at 7:16 PM
Jul 292009

If you’re working on Gecko, or Firefox, or Thunderbird, or really anything in the Mozilla universe that may impact developer documentation, there are a couple of things you can do to ensure that the relevant changes to developer documentation take place.

I mention this periodically in several forums, but it can’t be said often enough, so here we go:

First, if there’s a bug related to your work, make sure the “dev-doc-needed” keyword is added to the bug in Bugzilla. It doesn’t matter if you’ve actually made the change or not. The writers only apply changes to the documentation once the bug is both tagged as “dev-doc-needed” and the bug is marked as fixed. Until then, we pretty much ignore it.

Second, make sure the change that impacts developers is clearly explained somewhere in the bug comments. If necessary, add a new comment that explains what’s changed and why it’s relevant to developers, or at least says “Comments X, Y, and Z are relevant to developers.” This will reduce the likelihood that we’ll have to hunt people down and ask a lot of questions in order to ensure that the stuff gets written up adequately.

Third, if there isn’t really a good bug in Bugzilla on what needs to be written, feel free to file a new bug against the Mozilla Developer Center’s Documentation Requests component, explaining what needs to be written up. Useful information here includes links to the files that have changed (especially IDL), multiple relevant bugs, etc.

In all cases, including information about who would best be able to answer questions about the topic would be extremely helpful.

You can pretty safely assume that if your material isn’t either tagged as “dev-doc-needed” or filed as a bug against MDC, it won’t get written about. The sooner either of these is done in the development cycle for a given release, the more likely you are to get good documentation written, because this helps me schedule writing work to ensure that there’s time allotted for everything.

 Posted by at 1:40 PM
Jul 222009

Last night, our IT guys installed a new FCKeditor plugin on the Mozilla Developer Center that adds three new buttons to the toolbar. These let you more easily create definition lists; simply click the new “DefinitionList” icon to start a list, then use the “DefinitionTitle” and “Definition” buttons to switch between the two.

I’ve requested that they add code to automatically switch back and forth between the two as you press Enter. Hopefully that will happen, as it will make this much easier to use. Still, this is going to make life at least a little better. My thanks to the kind folks at MindTouch for putting this code together for us!

 Posted by at 9:59 PM
Jul 142009

I’ve started to work on reorganizing the XPCOM interface documentation on the Mozilla Developer Center. I’m going through every interface reference document, checking the tags, and moving them all into a new subtree in the documentation, rooted at “en/XPCOM Interface Reference”. Things are likely to be dusty for a while while I work on that.

I’ll be writing a script sometime in the next few days that will automatically populate the root page for the reference based on the subpages, so that we won’t have to manually add things to it. I’m tinkering with some ideas on that front.

I’m also tagging articles as I look at them with tags such as “NeedsContent” or “NeedsMarkupWork” and so forth, so that we can go back and fix articles that need revision work.

I know we already have an “XPCOM API Reference”; I decided that I’d rather start over than try to figure out where we left off with that, so everything is going to migrate into the newer setup from there.

Once the initial migration is done, there are two major chores that will need doing.

First, we need to get the rest of the interfaces documented. There are tons of them that aren’t yet.

Second, we need to go through and clean up the existing documents. Some are fine as they are, others are barely even a shell, and some are literally “Hey, we need to write something here” pages. Ugh. Hopefully the tagging work I’m doing will make it easier to go through all of these and clean them up.

Anyway, in the meantime, there’ll be some funny redirects and the like going on, I expect, and a flood of entries in the change history for MDC.

 Posted by at 1:06 AM
Jul 102009

I just got word from IT that they’ve updated the Mono runtime being used on the Mozilla Developer Center to version 2.4. This update was recommended by MindTouch; they believe that the outages we’ve had lately have been caused by a particular bug in the previous version of Mono that we were using.

In particular, apparently the version of Mono that was previously installed was leaking thread handles, resulting in it eventually not being able to spawn new tasks, and therefore ceasing to respond.

So my fingers are crossed, and I’m hoping it works!

 Posted by at 4:06 PM
Jul 012009

We’ve deployed our new editor plugin on the Mozilla Developer Center this afternoon. It currently doesn’t do a lot, but what it does is — at least for me — very nice.

When you open the editor on MDC, the table of contents sidebar now disappears, allowing you to use nearly the full width of your browser window for editing the article’s content. When you close the editor (either by saving your change or canceling the editor), the sidebar returns automatically.

This is especially helpful because the sidebar would often get in the way while editing tables and other wider formatted content, including code samples.

Now that Firefox 3.5 is out the door, I plan to ramp up work on back-end stuff even further, including adding more capabilities to our plugins; in addition, I’m gearing up on some organizational work, and talking with Mindtouch about implementing some scripts to help automate more administrative tasks.

 Posted by at 4:31 PM