Jun 302009
 

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!

 Posted by at 12:30 PM
Jun 222009
 

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.

Judging from the sorts of things they’re working on as the primary features for this release, I suspect they’re doing this work for one or more specific corporate clients (other than Mozilla), since of the major work they’re doing, none of it appears to correspond to anything on our wish list. One or two of these items do look like they might be potentially interesting, but they’re not well specced out yet, so we’ll see.

However, looking in their bug database, we can find an assortment of bugs I reported that are tentatively planned to be investigated — and hopefully fixed — in the Minneopa release. Being targeted for the upcoming release is of course not a guarantee, but it’s a hopeful sign.

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!

 Posted by at 3:07 PM
Jun 192009
 

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.

 Posted by at 2:00 PM
Jun 192009
 

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.

 Posted by at 11:04 AM
Jun 172009
 

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

First, we moved the “Page Notifications” box so that instead of being next to the page title, it’s at the top of the Table of Contents box. This fixes the problem that was causing the edit area to be annoyingly narrow.

Second, we fixed the missing resource string errors that were appearing in a couple of places.

Third, we installed a new MindTouch plugin that we developed. Currently, all this does is add some explanatory text to the new user registration page, explaining some policy information.

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.

 Posted by at 7:12 PM
Jun 112009
 

Here are three photos of things I saw today that amused me.

This one, I’ve seen actually many times over the last few years — the sign at my dentist’s office:

I find it amusing that my dentist’s office is on Crest Road.

Then there’s this one:

Typos on signs amuse me.

Then there’s this bumper sticker, which unfortunately is hard to read in this picture, courtesy of being taken from too car away with a cell phone camera:

“Things get better with age… I’m approaching magnificent!”

 Posted by at 12:03 AM
Jun 042009
 

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.

 Posted by at 4:14 PM
Jun 042009
 

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!

 Posted by at 10:50 AM
Jun 012009
 

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!

 Posted by at 2:37 PM