Near miss

 Personal  No Responses »
May 152009
 

This post by Wil Wheaton reminded me of an incident that happened a few years ago, back when we were still living in California.

Sarah and I had booked a place up in Tahoe for our anniversary, and were on our way up that way from our house in Tracy.  I was driving her pickup truck (which at the time was the vehicle we had that would best handle potentially ugly weather conditions up in the mountains), and we were on Interstate 5, driving north, just maybe 10 minutes out of home, when we saw there were some cars parked on the grass in the median and a fire truck parked along the right side of the freeway.

There wasn’t much activity going on, and traffic wasn’t slowing down, so I kept in the left-hand lane, which is where I was, and maintained my speed, keeping an eye on the cars in the median to make sure nobody did anything nuts like leap out onto the pavement.

Suddenly, without warning, the fire truck whipped off the right shoulder and lurched across the freeway, almost entirely perpendicular to the roadway, and essentially stopped in the middle of the road, blocking both the left and center lanes of the three-lane surface.

There was a car to my right, so I couldn’t pull over that way, and there was certainly no time to stop, so I hit the brakes — as much as I dared — and whipped the steering wheel to the left, surging off the pavement and onto the median.

This is where things got even hairier — fortunately, everything felt like it was happening in slow motion, because I needed it! Now I’m dodging the fire truck on my right, which while moving slowly is still trying to cross the freeway, as well as the cars and people hanging out in the median.

I managed not to hit anything, although I’m pretty sure we went up on two wheels as we skidded at a disturbing angle along the gravel shoulder and onto the grass, before I managed to angle us back onto the freeway after we passed the fire truck.

Back on the freeway, I eased us over to the slow lane and we were very quiet while I drove to the next exit, got off the freeway, parked behind an Exxon station, and then proceeded to shake violently for about 15 minutes before I finally was able to collect myself enough to resume driving.

The rest of the trip passed uneventfully.

It was… extremely scary. Gives me the heebie-jeebies to think about it even now, something like 7 years later.

 Posted by at 10:31 AM

Mouse gesture events now documented

 Firefox, MDN, Mozilla  No Responses »
May 132009
 

I’ve just finished the documentation for Gecko’s support for mouse gesture events, and would appreciate any feedback or edits you might have to suggest.

There are two articles:

Feel free to fix any errors or add an example. If there’s anything you see wrong that you’re not sure how to fix, drop me a note and I’ll see what I can do!

 Posted by at 8:39 PM

Touch typing

 Geekology, Personal  No Responses »
May 132009
 

I got my start on computers way back in fourth grade, which would be, um, 27 years ago.  I was a hunt-and-peck typist at first, of course.

Fast forward to 1987. I’m still not a touch typist, despite having been using computers to write code, school reports, and the like for six years.  This is now my sophomore year of high school, and the year I took typing class in school.

It didn’t do me a bit of good. Several months of typing class, and I still couldn’t type without looking at the keyboard. Sure, I could type with my fingers resting on the home keys, but if I didn’t look at my fingers while I typed, I was beyond useless.  All those typing drills and speed drills only taught me how to pretend not to be looking at my fingers while in fact not taking my eyes off them except when the teacher was looking.

I continued to be largely a hunt-and-peck typist — a fast hunt-and-peck-typist, but hunt-and-peck nontheless — for the next few years.

Then, one day, I guess it was my second year of college or so, I was sitting at my keyboard in my room, pounding out some code, when suddenly it hit me like a ton of bricks. I was sitting there typing — fast — and not looking at my fingers.

I don’t know when the transition from hunt-and-pick to touch-typing happened.  It clearly happened sometime in late high school or early in college, but for the life of me, I couldn’t narrow it down more than that. All I know is that after something like 10 years of typing, I was finally touch typing.  Might have been 8 years, might have been 12.  I have no clue beyond that.

My style isn’t exactly what the teacher drilled into us.  For example, I never use the right shift key, even though we were supposed to use it when shifting keys on the left side of the keyboard.  On the other hand (no pun intended), I always use my right thumb to hit the space bar, even though we were taught to alternate.

Still, as someone that spends upwards of 12 hours a day at a keyboard, I’m glad this skill finally managed to wind its way into my nervous system and take hold.  Being able to see what you’re writing pour out onto the screen without having to look up from your fingers makes it a lot easier!

 Posted by at 7:30 PM

Why we’re waiting for MindTouch 2009 9.02.2

 MDN, Mozilla  No Responses »
May 132009
 

After announcing, then unannouncing, our plans to upgrade to MindTouch 2009 this week, I figured I should explain why we’re waiting for the 9.02.2 patch that’s coming next week.  The main reason we’re delaying the upgrade is because a cross-site scripting bug that we’ve applied a custom fix for in the version of MindTouch we’re using currently is not fixed in MindTouch 2009 9.02.1, but is in 9.02.2.

There are plenty of other fixes that are interesting (from our perspective, anyway).  These include:

  • Custom new user page templates don’t get processed, but are simply embedded. This should be fixed for 9.02.2.
  • They removed the Special:About page from 9.02; once they realized that end users actually may need to see the info on those pages, it’s returning in 9.02.2.
  • Support for using syntax highlighting without line numbers. We’ll use this for some samples that are very short.
  • Filtering popular pages by language will be supported.
  • Search results won’t include templates, by default.
  • The MIME type for JPEG files is fixed; this will fix problems with JPEG images not rendering correctly in certain browsers.
  • Currently, using parentheses in searches results in a lucene error; the update should escape the search string if an error occurs and try again.
  • Page change alert notifications (a new MindTouch 2009 feature we’ve been excited about) are improved significantly.
  • A browser-crashing bug in the editor has been fixed.
  • A bug causing Google Analytics code to be added to pages even though GA support is disabled is fixed.
  • You should be able to subscribe for notification of changes to a page (and optionally its subpages) when you create a new page. This is an improvement to a new feature in MindTouch 2009.
  • Canceling editing the Talk page when it doesn’t previously exist should now return you to the corresponding article instead of back to the Main Page.

Some of these have not actually been fixed yet, so it’s possible that not all of these fixes will reach us when 9.02.2 drops next week. I hope so, though!

 Posted by at 3:52 PM

Oops – I got ahead of myself a bit!

 MDN, Mozilla  No Responses »
May 132009
 

I forgot that we’re actually waiting for MindTouch to release MindTouch 2009 9.02.2, which is due out late next week. So the upgrade is on hold until that’s out the door, then we’re going to roll out the upgrade I just talked about in my last post. I’ll blog again once we reschedule that.

 Posted by at 2:41 PM

MDC upgrade to MindTouch 2009 scheduled

 MDN, Mozilla  3 Responses »
May 132009
 

We’ve now scheduled the upgrade to MindTouch 2009 on the Mozilla Developer Center site! Our friends in IT have slated the upgrade to take place during this Thursday’s scheduled maintenance window (that’s May 14th).

This upgrade, once complete, will net us a number of crucial improvements, and will include back-end capabilities we’ll be leveraging soon as well.

Some of the key benefits we’ll get out of the new upgrade:

  • An improved diff feature. While I’ve made changes to our skin to support this, I think there may be a couple more that need to be done to best take advantage of the changes.
  • The recent changes page now has links directly to the diffs.
  • RSS feed entries have been changed to only show the portions of the content that have changed, instead of the entire article.
  • Talk pages now have a link back to the article they’re about.
  • You can now add edit comments to edits when you save them.
  • Search results now default to only showing results for the user’s preferred language, but can be changed to show results in other or all languages.
  • New tools for change notifications; we can now assign people to be notified when specific articles or hierarchies of articles are edited; this will soon be getting used to automatically request technical reviews from subject-matter experts.
  • Users can now disable search term highlighting on search results pages.
  • We’ll be able to clean up table of contents displays so they don’t show crazy deeply nested lists of headings.
  • Table of contents links are now simply links to the in-page anchor instead of a full URI. This will eliminate a lot of cases of pages reloading instead of just scrolling when navigating.

There are a number of other things, but these are the ones that come immediately to mind.

 Posted by at 2:13 PM

New MDC content: Pixel manipulation with canvas

 Firefox, Mozilla  2 Responses »
May 122009
 

Today, Paul Rouget pointed out that the Firefox 3.5 for developers page didn’t mention the newly-implemented createImageData() method.

While looking for the right place to add documentation for that method, I realized that we had no documentation at all for using the ImageData object to manipulate pixel data in a canvas.  So I settled in and wrote Pixel manipulation with canvas.

This is one of those times when documenting a new feature (the createImageData() method) led to writing content about previously existing features (all the other ImageData methods). Everybody wins!

 Posted by at 11:23 AM

Thoughts on automated documentation generation

 Mozilla  9 Responses »
May 112009
 

This morning I finally got around to fixing numerous problems with the Gecko binary stream documentation. The articles for both nsIBinaryInputStream and nsIBinaryOutputStream were pretty whacked, with totally incorrect descriptions for a number of methods, plus methods completely missing in some places.

These two articles were converted from automatically generated documents, and the result exposes some of the inherent limitations to automatic documentation generation.  If you look at the IDL for these two interfaces, you’ll see that the comments are not very thorough. Individual methods have no comments; instead, the comments are for groups of methods (at best). In addition, not all parameters have comments describing them.

The result is that the importer tool has to make guesses in a lot of cases, and the results are often sub-optimal.  In this case, the last available method-describing comment was duplicated for each method added to the document, resulting in every method in nsIBinaryInputStream being listed as returning Boolean value read from a single byte from the stream.

While there’s certainly a place for automated tools in documentation, there always needs to be a human reviewing the output, because unless you can guarantee that the comments and markup in the IDL files is correct, the output won’t be.  It’s clear that these two articles, for example, were never really reviewed.

This is why I prefer to take a slow and measured pace as we investigate automation of documentation tasks. It’s very easy to automatically generate bad documentation. It’s very, very hard to automatically generate good, reliable documentation.  In my opinion, it’s not worth doing if you can’t do it right.

That’s why my feeling is that using tools to do an initial, automatically generated rendition of a document is fine, but from then on, it should be maintained by human writers and editors. That way, we can better control quality. And every article needs to be reviewed by at least one human editor as well — preferably both a writer and an engineer — in order to ensure accuracy.

I’d like to have a tool that can take IDL input and generate output formatted following our interface reference style guidelines. Then we can clean up the output and post it. That would help us get our content filled out faster. We just can’t blindly post everything it generates.

 Posted by at 4:51 PM

Productivity slowly returning

 Firefox, MDN, Mozilla  2 Responses »
May 052009
 

I returned home from the Mozilla all-hands meeting late last week with a cold, which has gotten progressively worse.  I think I’ve gotten through the worst of it as of today, so I’m gradually starting to gain productivity back. Hopefully in the next day or two I’ll be more or less back up to full speed.

While I’ve not been super-productive, I have managed to get a few things done. We’re gradually making headway on our preparations to roll out the MindTouch 2009 upgrade on MDC. Last week, IT set up a clone of MDC, which we then upgraded.  We’re working out the hiccups from the upgrade now, and hopefully will start testing it in the next few days.

I’ve also started doing some “pick up” documentation for Firefox 3.5 and Gecko 1.9.1; things that nobody noticed needed documentation until fairly late in the process.  Among these is our now-closer-to-spec implementation of border-radius.

There are plenty of other things on my plate to work on, but I’ll get to them as I get to them. For fairly obvious reasons, stuff related specifically to Gecko 1.9.1 and Firefox 3.5 is highest on my to-do list at the moment.

However, I’m also doing some forward-thinking on infrastructure work. I hope to start introducing even more interesting and useful new templates over the coming weeks. I’ll blog about what I’m doing on that front soon!

 Posted by at 5:27 PM
 Newer Entries