Archive for the 'Mozilla' Category

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.

Firefox 3.5 was released about an hour and a half ago, and downloads are going strong. Seems like a good opportunity for me to thank everyone that contributed to the documentation for Firefox 3.5. While there are far too many people to thank them all by name (so I won’t be calling anyone out by name today, to avoid leaving anyone out), I’ll call out a few specific groups of people:

• Thanks to all the developers that made Firefox 3.5 all kinds of awesome. It’s because of you that we had so much writing work to do for this release!
• Thanks also to everyone that wrote content for the Firefox 3.5 documentation. This includes not just the folks that wrote articles on the wiki, but also people that blogged about new features and about fixed bugs, because your blog posts helped us get the documentation whipped into shape.
• I’d also like to thank people that helped tag bugs with the “dev-doc-needed” keyword so that we’d know what needed to be written about, as well as folks that filed bugs against the documentation.
• Last, but not least, I’d like to thank everyone that offered feedback on the documentation, as well as the folks that were so helpful when I had questions about the technical details.

The quality of our documentation rests largely in the hands of our engineers and contributors; there’s far too much for me to get it all right by myself, so thanks to everyone for your help!

For the next little while, while the plan for the next release is still coalescing, I’ll be working mostly on back-end stuff, such as our MindTouch wiki add-ons, as well as organization clean-up work. My goal for the next few months is to make the Mozilla Developer Center easier to use, as well as easier to contribute to.

I’d like to remind everyone to start tagging relevant bugs for Firefox.next as dev-doc-needed! It’s never too early; we’ve already got some docs for Gecko 1.9.2 on MDC!

For obvious reasons, I keep a close eye on MindTouch’s development plans, and have been watching their planning work on the “Minneopa” release tentatively scheduled to ship in late July. This is a pretty short turnaround from the “Lyons” release that shipped just a couple of months ago, which is the one we’re currently using.

The things from my wish list that are tentatively slated to be worked on for Minneopa:

• The side-by-side diff view, which currently lists the entire article side by side, which limits its usefulness, will hopefully only show the blocks containing changes, instead of the entire content.
• The link editor dialog will hopefully get some love; it needs some!
• Currently, if the wiki encounters timeouts while communicating with the database, it can become unreliable, even after the database returns to normal. Hopefully progress will be made on fixing this; if nothing else, they plan to complete some refactoring of the database code that should make it more reliable going forward. With luck, just doing that will help with this problem.

There are several other items that I’ve filed tickets for that they plan to look at for the Minneopa release, although they’re not on my major concerns list.

At this point, these are:

• Currently, if the login cookie disappears while you’re editing, trying to save instead loses your work.
• We’d like to be able to add customized descriptive text to any Special:Tags page, so we can use them as category pages that offer introductory text.
• Special:Tags pages currently show page titles with spaces even if the titles have been overridden to use underscores.
• The edit summary entry field is currently very narrow; they will hopefully widen it for us.
• I’ve requested the ability to disallow the invention of new tags in the tag editing feature for pages; instead, tags will hopefully be created using a separate interface accessible to certain trusted users, and when tagging articles, users will only be allowed to use pre-defined tags. This will hopefully improve the validity and usefulness of tags by ensuring that tags are used more consistently.
• Currently, links to talk pages that have no content are rendered as normal links, instead of “no content” links. This means people will follow the links hoping to learn more, only to be disappointed.
• The feature that lets you recover your password currently requires you to type spaces instead of underscores, even if you used underscores when creating your username. This should be fixed.
• We requested an option to allow image and file management for articles to be handled on a separate page from the article page itself, so that you don’t have the “Images” and “Files” sections tacked at the bottom of articles. This would make the interface for people not editing the content cleaner, but I’m no longer certain we’d use this. I’d like opinions!

Hopefully more things will make their way in, but given the short schedule for this release, I don’t expect miracles. With luck, once this update is out the door, they can start working on more of our big requests!

Still, just getting the improved link editor and side-by-side views will be big wins for ease-of-use for us, I think.

And, again, keep in mind that there’s no guarantee that all of these things will actually be addressed in this release! I don’t want people whining to MindTouch (or to me, actually) if anything gets cut from this short timeframe release!

Lately I’ve been thinking more about my place in the developer relations team at Mozilla. It’s sort of an odd place for me to be, sometimes. While my work managing the Mozilla Developer Center is obviously a component of developer relations, in past organizations I’ve worked in, technical writing was actually part of the engineering group.

Developer relations

Sometimes while I’m sitting in meetings, I find myself feeling vaguely adrift, since a lot of what goes on doesn’t all that directly relate to what I’m doing on a day-to-day basis. While my work involves interacting with developers, it’s generally on a different level than most of the rest of developer relations. I’m more interested in getting down information than in what exactly people choose to do with it.

To be honest, the sort of public relations work that a lot of developer relations involves — while incredibly important — isn’t really my forte.  I’m glad we have a bunch of folks that are both good at it and enjoy it, because that’s certainly not me!

Engineering

On the other hand, attending engineering meetings can be an interesting experience for me. As a writer, I’m in the complicated position of needing to know what’s coming while avoiding knowing too much about things that are in a state of flux.

For example, let’s say a new technology is being introduced in the next version of Gecko. Great! I’ll need to write about that, of course.

The problem is this: when do I start studying up on it? If I start learning the technology too soon, I risk learning details that may change over time, requiring re-learning stuff later when the specifics change.

This happens fairly often. For that reason, I try to wait until a technology appears to be entering a relatively steady state before starting to learn details about it, let alone write about it. There’s probably nothing as frustrating as writing documentation about something only to have to redo it all because of drastic changes to an API.

However, I have to balance that with the need to have the documentation ready by the product’s ship date, and preferably by around the time it enters beta, so that developers have the material in hand when they need it.

It’s a tricky fine line to walk, but I like to think I’ve mostly done a good job of this. Our documentation for the releases of Firefox (and by extension, Gecko) that we’ve shipped since I joined Mozilla four years ago has generally been pretty good. Especially given the enormous amount of material there is to cover!

Between worlds

So basically, I sometimes feel sort of adrift between engineering and developer relations. Maybe that’s the right place to be. I don’t know. I suppose it helps to ensure I’m in touch with everyone I need to be dealing with.

But occasionally it can be slightly frustrating, too.

I’m not sure there’s anything that can be done about that. Writing developer documentation is a strange world to live in. It’s exciting and rewarding work, though, and I feel like I found my calling when I took my first technical writing job, which, ironically, I took because it was the only job I came close to qualifying for at a company I badly wanted to work for, and not because I was specifically looking to be a writer.

If you haven’t been following the Mozilla hacks blog, where we’re featuring 35 days worth of Firefox 3.5 improvements for web developers — including tons of awesome demos and clever tricks — you’re missing a lot of great stuff.

The stuff being shared on the hacks blog is a preview of sorts of the direction in which the Web is going. Armed with the stuff going on there, you’ll be able to do stuff that previously simply couldn’t be done without resorting to tedious and/or proprietary techniques. Now you can do wicked cool stuff using open technologies.

Today we installed a few minor tweaks to the Mozilla Developer Center web site.

We also installed a new plugin for the editor used by the wiki, but it’s not currently working. Once we figure out why it doesn’t work (it works in the test VM I developed the code on), we’ll fix it and I’ll go into more detail then.

As I continue to explore the latest changes to the Mozilla Developer Center, here are a few subtle — but useful — changes you may enjoy.

I’m hard at work to make more additions and improvements. One of these that should be landing soon is a feature that will automatically hide the table of contents sidebar while you’re editing articles. This gives you the full width of your browser window for editing, which not only gives you a broader canvas on which to write, but also presents your content more like it will appear when the article is rendered for viewing.

The code for that has been written; I’m working with IT to get it checked in and activated. We need to sort out the best way to manage it in SVN to ensure it stays up to date as we upgrade the MindTouch software in the future.

New keyboard shortcuts

Among the many keyboard shortcuts supported by the MindTouch editor, there are a couple of newly-supported ones that I find useful.

First, you can now press shift-space to insert a non-breaking space.

Second, and more useful, you can press shift-enter to exit out of the current block. For example, if you’re editing a pre block, shift-enter drops you out of the block so you can resume editing the body text.

Saving from source mode

You can now save your changes while in source editing mode. This is a big improvement; previously, if you were editing an article’s raw XHTML code, you had to switch back to the WYSIWYG view before you could save your changes. It was quite frustrating. Now it’s all better!

Paste as plain text

Next to the Cancel button in the second row of the toolbar is the new “Paste as plain text” button, which pastes the contents of your clipboard with all formatting stripped out. This makes copying and pasting from one place to another much easier. Sometimes you do want to keep all the styling and links, but often you don’t. Now you can do it either way.

Create div containers

It’s now easy to create a div block using a new popup div editor. You can choose among styles to apply to the block from a list, or use a more advanced form to build a custom block. You can also still drop into the source editor to do it if you like, of course.

Yesterday we applied a new skin change that exposes a couple more new features.  Today, let’s take a look at them!

Page notifications

The new Page Notifications box can be found to the right of the article title. It looks like this:

Clicking on this pops up a list of notification options:

From here, you can choose whether you want to be notified of changes for the current page or that page and all its subpages.

This should prove to be very useful — with this feature, we can start making progress toward having subject matter experts watch the site’s contents for changes to ensure the content remains accurate.  I’ll want to experiment with this a bit before I start asking people to sign up for notifications, although of course people are welcome to go for it if they like.

New tag editor

The new tag editor will hopefully help people find and apply appropriate tags to articles a little bit better. Previously, clicking the “add or edit tags” button popped up a dialog in which you would type in all the tags. Now tag editing is done inline.

Underneath the list of tags for the page is a new “Edit tags” link. Clicking that activates the new inline tag editor:

When you mouse over each tag, a button appears that lets you delete the tag from the list. Adding a new tag is as simple as typing it into the edit box and pressing the return key.  A nice touch is that the tag entry box autocompletes based on existing tags:

This helps make it easier to track down the tag or tags you want to add to the article.

When you’re done editing tags, click the “Return to view tags” link to close the tag editor.

This isn’t a perfect solution; what I actually want to eventually have is a separate interface for creating tags, so that we have a predefined list of tags, and then to only allow those tags to be used. We get a lot of people creating bogus tags, often filled with spam, and they get quite frustrating to clean up every day!

I’ve just changed the Help link at the top of the Mozilla Developer Center site to link to a new article entitled “Using the Mozilla Developer Center.”

This article provides helpful tips and techniques, from “as a wiki, you can edit it yourself if you see problems” to “you can do wicked cool stuff with Lucene search queries”. It also includes a link to the previously existing, but now upgraded, “MDC editor guide,” which offers information about keyboard shortcuts, the toolbar, and more.

Hopefully these will help people learn to make better use of the Mozilla Developer Center.

Let me know what you think!

So we got the Mozilla Developer Center upgrade done last night, thanks to the awesome dudes in IT! Over the next few days, I’ll be blogging a bit about the things we gain from this upgrade, from the major stuff to the little stuff (and not necessarily in that order).

Things that need doing still

There are a few things left to do; I’ll be revamping our editor toolbar today to make the editor more convenient to use. I’ve got a better feel now for which features we use and which we don’t, so I can make a better toolbar than the one we currently have.

There are some skin changes I need to make to support new features; for example, we currently don’t support the new notification system because our skin doesn’t expose it to the user. That’s an oversight on my part; I forgot to add support for that to the skin before the upgrade, but I’ll be working on that over the next few days.

In addition, there’s a new tag editor that in theory provides a nicer interface for editing tags, but at present looks awful because we haven’t skinned it yet. I’ll be dealing with that too.

Also, some under-the-hood changes have been made to how custom string resources are stored; previously, we had to manually append our custom strings to the standard resource files every time we updated the software. Now they’re kept in separate files. We haven’t moved them into their own files yet, because we weren’t aware of this capability at the time. We’ll be doing that sometime in the next week or two, once we work through the other stuff that needs doing.

A few improvements

A much-requested improvement that we have now is that the version comparison page now shows you the two versions side-by-side, instead of intermingled and hard to read. The RSS feed still does it the old way, but this is definite progress!

Another helpful improvement is that when you’re editing, there’s now an “Edit summary” box at the bottom, where you can enter an explanation of what you’re changing and why. This is a much-requested feature that we definitely missed when we switched away from MediaWiki, and I’m thrilled to have it now!

One small but pleasant change is that, finally, when you enter edit mode, there’s no longer a spurious extra scroll bar. Instead, the edit box is scrolled along with the rest of your content using the main scroll bar on the browser window. In addition, the edit box more reliably resizes along with the content you’re editing. This will make the editing experience much more pleasant, I think.

There is now a “View page” link on Talk pages that takes you back to the main article; currently, it’s being drawn dimmed as if it’s disabled (due to a minor MindTouch bug that I’ve filed a ticket for), but the button does actually work.

I’ve also configured the table of contents that draws in the top-right corner of pages to only show the top three levels of headings; this prevents certain pages — especially interface references — from having unreasonably long tables of contents, leaving them much easier to navigate.

The RSS feed for new changes on the wiki now only shows the blocks that have changed, instead of embedding the entire article. It also calls out each individual edit, instead of lumping all edits together, leaving you to guess who made what changes.

One thing you can do — which I think you were actually able to do in the previous version, but I never mentioned before — is subscribe to RSS feeds for individual pages and subtrees of the site; click the RSS feed icon in your location bar, and the popup that appears lets you choose between the “What’s new feed” (for all changes on the wiki), the “Page and subpages changes feed” (for all changes in the subtree of the site rooted at the page you’re looking at), and the “Page changes feed” (which only covers changes to the page you’re looking at).

That’s not the same as the excellent notification system that we’ll expose soon, but it’s still a handy feature.

But wait, there’s more…

There are other changes, too, but these are the ones that come immediately to mind. I’ll go into more detail, and discuss other changes, in future blog posts over the coming days and weeks.  But this should get you started exploring the improved Mozilla Developer Center!