Dec 052012
 

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.

Filters

At the top, there are filtering options.

Screen shot of the filter list

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:

Revision list

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.

Screenshot of the article list

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.

Revision diff

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.

Screen shot of the diff area

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.

Expect change!

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!

 Posted by at 11:44 AM
Nov 152012
 

We’re having a virtual — that is, online — MDN documentation sprint from November 30 through December 1! We encourage anyone interested in helping make documentation of and for the open Web to log onto #devmo on irc.mozilla.org and help out. Even if you only have a few minutes, it’s possible to make a huge difference. Indeed, if you’re a Web developer that knows lots of things, you can log in and help answer questions the writers might have. That’s a way you can contribute to MDN content without doing any writing yourself!

Check out the wiki page about this doc sprint and put your name on the list if you plan to participate. There’s even a list of links to suggested topics for work. And you can even contribute by simply adding live samples to existing articles, using our nifty new live sample system!

I hope to see you there! We always have a good time and get lots of great work done to make developing for the open Web easier for everyone!

 Posted by at 7:30 AM
Oct 052012
 

Note: You may see “documentation process” and think this doesn’t apply to you. You’re almost certainly wrong! If you contribute to the Mozilla project, this almost certainly does apply to you, so please read on!

The short version

Because the rate of development at Mozilla is accelerating faster than the MDN developer documentation team can keep up, it’s time for us to establish a process by which development teams request that the documentation team produce content to cover new features, APIs, and technologies. I have produced a document that outlines a proposed new process by which this will be done, outlining how documentation requests will be handled and prioritized, how we will interact with the developers, and the responsibilities of the writers and the developers in terms of getting the documentation produced.

The long version

Mozilla developers rock. Like… they rock hard. Odds are, if you’re reading this, you’re one of those amazing developers. If you are, you need to understand, first off, that the MDN team knows you’re almost frighteningly good at what you do.

Because of that, we’re totally swamped! With so many amazing new technologies and APIs coming from your keyboards to our to-do lists, we simply can’t keep up. As Mozilla has grown, the amount of material that the developer documentation team needs to produce has skyrocketed. Think about it: we’re documenting one of the most popular Web browsers in the world, a popular e-mail client, open Web standards from HTML through CSS and JavaScript to new technologies like WebAPI, how to write games and apps online, a brand new mobile operating system (Firefox OS), concepts like security, identify management, and the like, and more.

And we do it with a paid staff of four full-time and one part-time writer and a community of contributors who, while amazing, can’t always have the time to document this much cool stuff.

Most large organizations that have technical documentation requirements have a process by which that happens. Mozilla never has; we’ve done our documentation in a very free-form way: a writer sees something needs to be documented and writes about it. A lot of things fall through the cracks because the writers didn’t know they existed, or were ready for documenting.

The time has come for that to change. In an attempt to improve the responsiveness of the documentation team, increase both the quality and the quantity of material we can produce, and help enhance communication between the development and writing teams, I have proposed a documentation process by which development teams will request that writers produce material for their work.

I urge you, if you contribute to Mozilla, to read the proposal and offer your thoughts. I think this will help everyone. Our developers will see their work get properly documented both better and more quickly. Our writers will be able to avoid wasting a lot of time searching for information they shouldn’t have to search for. And our users will get top-notch documentation for the amazing Web of the future.

To offer your feedback, you may either post to the mozilla.dev.mdc mailing list, send me email, or comment on this blog post.

 Posted by at 9:26 AM
Jun 292012
 

Kuma, the new wiki platform Mozilla is building for the Mozilla Developer Network, is going to be deployed in stages starting on July 5th. As I mentioned yesterday, that day we will direct all attempts to edit the site to the new Kuma site, while viewing will continue (by default) on the current one. Then on the 15th, we will begin directing all traffic to Kuma instead, and it will become the new powerhouse driving developer.mozilla.org.

However, we haven’t really shared a lot of details yet about what features you can expect from the new site. Let me start to fix that! I’ll be blogging over the coming days about the new stuff you’ll see.

First, let me begin by saying that the site will look very familiar if you’re reading it. Indeed, as a typical user, you may not even notice any difference! It’s possible that you may find the occasional glitch, where something hasn’t been updated fully to work correctly on the redesigned site. But we’ll be continuing to work on cleaning those things up.

Indeed, it’s worth keeping in mind that our development team will continue to improve Kuma at a rapid pace over the weeks and months following our launch!

Okay, on to a few of the things that typical users will see.

Reviews

First off, you may find pages with banners at the top that look like this:

An example of what the review needed boxes look like

That’s because we now have a more formal system of requesting technical and editorial reviews. Whenever a user edits an article, there are checkboxes that they can use when submitting their change to request that someone review the content; this replaces our old system of using “NeedsTechnicalReview” and “NeedsEditorialReview” tags (although those tags have not yet been converted to use the new system).

If you review a page, you can simply turn off the appropriate checkbox on the edit page and save the page. Boom! It’s reviewed!

Contributor list

The only other really obvious change is that at the bottom of the page, you’ll see a list of all the people who have contributed to the article! This little tip-of-the-hat to our community is fantastic! Clicking on the username takes you to their MDN profile page.

More news to come!

Other than these changes, you probably won’t see much difference. There aren’t as many options in the drop-down menus right now, but that will change as our feature set expands. The real changes are going to be visible to our writers and localizers. I’ll be talking about those changes starting tomorrow.

 Posted by at 12:51 PM  Tagged with:
Mar 162012
 

The last week or so, I’ve been working on sample code for the Source Editor API. While this API is not incredibly mission critical, in that it doesn’t directly affect web developers, and isn’t in the critical path for documentation, I’ve enjoyed this work, and the time spent writing about it — and, more importantly, building sample code for it — has been educational.

One thing that occurred to me is this: we need more real-world examples of how to do things. Too many of our examples are simple, fictionalized snippets of code that don’t show you how to do things in the greater scheme of getting things done. However, you still need to document things in context, too.

What I propose is this: what if we set up a section on MDN for larger examples of all kinds, where each page is a complete example, with downloadable code and one section for each method or interesting section of the example, talking about how it works? Then we can link to those sections from the relevant documentation site-wide.

For instance, this example I’m working on shows how to do all of the following things:

  • Create a new XUL window
  • Import several JavaScript code modules
  • Add a Source Editor to the window
  • Interact with the Source Editor
  • Create and manage a menu bar
  • Check and uncheck menu items given the state of the source editor
  • Update the display in a status area of the window given information obtained from the source editor
  • Asynchronously fetch the contents of a page using NetUtil
  • Overlay XUL from within the browser into the source editor to re-use UI and code
  • Save the text from the source editor to a local file on disk
  • Display alerts using the prompt service
  • Call various methods from XUL definitions of UI
  • Add and remove event listeners
  • Some parsing of file and pathnames
  • Set the title of a window based on the name of the item being edited
  • Add an item to the browser’s content area context menu under specific conditions

That’s a lot of stuff, and being able to demonstrate how all of those things are done in a real-world extension has a lot of value. By having a page that covers all of the things this add-on does, then being able to link to the appropriate parts of that page from all over the site, we can really bring our documentation to a whole new level.

Any thoughts?

 Posted by at 7:30 AM
Feb 292012
 

A few months ago, we decided to set up a driver system for driving documentations on a release-by-release basis, with a writer taking lead on each release as it made its way through the release train process.

This… didn’t really work out. It was a noble experiment that failed.

We’re now in the process of switching to a per-topic documentation driver system. This will let us get documentation for the most important material done more quickly (at least in theory) regardless of when it ships. The driver for each topic area will prioritize the work for that subject matter and help ensure that things get written when appropriate. They’ll help coordinate the writers that are interested in contributing to that topic and make sure that the docs in that area of the wiki are kept tidy and are properly crosslinked.

Obviously, the first step in switching to this driver model is to get people selected for each of the topic areas. We have a new page on the wiki for this. If you know of a topic area that’s not listed there (or is a large enough subset of one of the ones already there that it should be handled separately), please feel free to add it. Similarly, if you’re interested in being a documentation driver for one of those topics, let me know, or put your name down.

I’ve not yet selected the topics I will drive, other than likely the XUL and XPCOM stuff. I’m waiting to see what others would like to do first (indeed, if anyone else wants those two, feel free to take them from me). My primary goal as always will be to coordinate the overall documentation effort, maintain the site in general, and contribute as needed, in addition to driving whichever topics I wind up with.

If you have questions or would like to volunteer to drive a topic, feel free to comment here, send me email, or pop into #devmo on irc.mozilla.org.

 Posted by at 3:23 PM
Feb 282012
 

As pretty much everyone knows, our documentation for events (both standard DOM events and Gecko-specific ones) is pretty lame. We’re missing a lot of stuff, and what we have is often bad and poorly organized.

We have a new event reference page:

https://developer.mozilla.org/en/Mozilla_event_reference

Which embeds the Gecko and DOM event references:

https://developer.mozilla.org/en/Gecko-Specific_DOM_Events
https://developer.mozilla.org/en/DOM/DOM_event_reference

However, neither of these pages are complete, and most of the events have little or no documentation.

This is obviously important documentation, but has never managed to drift to the top of the to-do lists of any of the writers.

For that reason, we’re now looking for a contractor that we’d pay to write and clean up this material. The goal is to have complete documentation of all standard events for the DOM and other open web APIs, as well as for Gecko-specific and internal events.

This will probably take a while, although at the moment I don’t know how long. There’s quite a lot to be done; it would involve, among other things, going through the spec to find events and document them, plus going through the code to see which ones we support and which ones we don’t (as well as, hopefully, where our implementation deviates from spec).

Additionally, the writer would need to be able to look through the code to find, understand, and document the Gecko-internal events, most of which are currently entirely undocumented.

If you’re interested, or know someone that might be interested, please let me know!

 Posted by at 10:43 AM
Jan 272012
 

I love the English language. It’s crazy, complicated, and bloated, and those are all things that contribute to its amazing expressiveness. If a word doesn’t exist, someone will make it up, or rip it off from another language. It’s a quirky, twisted amalgamation of words and syntax from a broad swath of other languages. From Latin to German to Japanese and Cherokee, English has swiped words from dozens of other languages.

All of that makes it a tricky language to master. It’s not hard to get your point across in English, but to do it with an appropriate level of grammatical correctness and meet the style and formality of whatever context you’re working in can be difficult.

English can be ugly and twisted or fluid and beautiful, depending on the skill level of the writer and the point they’re trying to get across. It can be used to create magnificent works such as Handel’s “Messiah” and Shakespeare’s Hamlet, popular novels such as Stephen King’s Carrie, or technical materials such as the MDN wiki I administrate. If you look at all of these works, they demonstrate the wide variety of styles of material you can create in English, and they each practically feel like they’re written in a different language, because of how differently the construction of sentences and the flow of the material works.

That English can be difficult to master has the side benefit of making being a technical writer a very attractive and lucrative line of work. If you know how to write code and can also write in English easily and with skill, you have a unique suite of capabilities that make you highly employable. And if you love words, and have fun writing code, technical writing is a blast — being able to do both is the most fun I’ve ever had in my working life, and I’m incredibly thankful that I get to do it.

 Posted by at 4:06 PM
Jan 262012
 

As I came to the realization, which I mentioned in my previous post, that I was fed up with game development for a living, I had been playing with BeOS for a while, so I decided I’d like to work for Be. I went to their job listing page and looked through the list of openings. The only one that didn’t require a college degree (which I didn’t have) was one for a technical writer.

So I applied. A few weeks later, they let me know I didn’t get the job.

I got myself fired by the game company (due to my unwillingness to cooperate with a particularly bad business decision), and wound up at another one. About three weeks after starting that job, Be called back and asked me to come up for an interview. So I went up to the Bay Area and met with Doug Fulton and one or two other people up there (I don’t remember who all else, since there were several, and it’s been a long time). We chatted for a while, I felt I made a terrible impression, and I went home.

A few weeks after that, Be let me know that while they didn’t think I was qualified for the technical writer job, they’d bring me on as a junior writer if I was willing to do that. I jumped all over that, and my career as a technical writer began.

I started at Be in September of 1997, working out of the office in Menlo Park. I was the junior of three technical writers. One of them (whose name I agonizingly fail to remember) left not too long after I started, but Doug I remember. Doug had worked as a writer at NeXT, and would tell stories about how great his desk was being near the rear exit of the building so he could escape when Steve Jobs came in.

I had zero experience as a technical writer, so working with Doug, a long-time writer, was a great experience for me. He didn’t teach, per se, but offered a lot of guidance, and I watched how he did things closely as I got into the swing of things. If that experience hadn’t been such a good one, it’s entirely possible I might have fled technical writing back to programming, which probably would have been a mistake.

I’m a decent programmer — even a very good one, within certain bounds. But I like to think I’m a very good technical writer. Doug (and by extension, Be) gave me the opportunity to figure that out and spread my wings. By the end of my first year at Be, I was a senior technical writer and had had my pay bumped three times to match that title.

I’d found my calling at last. So thanks for the job, Doug.

 Posted by at 11:30 AM
Jan 252012
 

Back in the olden days, I used to be a programmer writing code for a computer game company. It was hard, unglamorous work, and once the initial excitement wore off, it really became “just a job,” rather than something I loved to do. However, what drove me over the edge into outright hating the entire industry was a particular project that led me to question not my own sanity, but the sanity of artists who thought they were game designers.

Let’s see if I can tell the tale without using names.

Back in the mid-to-late 1990s, lots of movie studios were setting up game development studios to take advantage of languishing properties that they might be able to turn a fast buck on by turning them into games, or, with luck, game franchises. One of these decided to take a family movie from the ’60s and see if they could get an educational game made out of it.

They selected a team of artists — the operators of an outfit in Southern California that produced 3D animation for commercials and other projects — to design this game. That was their third mistake (the second being their selection of a project, and the first being the setting up of an “interactive” division in the first place).

These artists came up with a game idea, got it approved, and subcontracted out the programming to us.

They then proceeded to ignore every bit of design advice we gave them about what was remotely possible using 1997 software technology targeting computers that would be commonly found in schools and homes with small children. We would have meetings explaining how their designs were not possible to achieve, and they would apologize and make changes that made things even worse.

Over time, their grand design did gradually get scaled back — not by removing the impossible features, but by stripping out vast chunks of the game, leaving what had been envisioned as some two dozen scenes with fun, interactive puzzles as just short of 20 screens with animations that would activate when items were clicked and a few mediocre not-really-puzzles. In order to accommodate their poor design choices, multiple versions of the various animation sequences were required to cope with the cases where two animations could overlap one another; we would then select the video to play based on how many animations were supposed to be running, and play one movie covering both animating objects.

On top of all that, their lusciously, beautifully rendered cartoon graphics (and, yes, the artwork was beautiful) would sing and perform, with really quite nice voice acting and music. Except often they would sing songs that included inappropriate lyrics. Then there was the dance that included moves so suggestive that when I first got the video files, my jaw hit the keyboard, and I summoned everyone else in our company to see it, upon which they had to collect their jaws off my office floor.

Not long after that, the designers decided we were so far behind schedule that they moved into our offices and set up a dozen SGI workstations on our conference table to render videos, so they could make all the adjustments needed as we pointed out all the ways they had violated the set of rules we gave them for what they could and could not do in order to pack all this stuff onto a single CD-ROM. It was around that same time that the project manager from the movie-studio-interactive company started hanging around our office despite our having no actual direct business relationship with them. That was awesome too.

By the end of the project, there had been four-day-weekends during which I got less than 3 hours’ total sleep, weeks in which I worked 170+ hours, and actual physical fights in the office. In addition, there was the time I literally fell asleep, face on my keyboard, and one of the designer guys saw me and yelled at me for sleeping, despite having been there for over 20 hours.

As that project wound down, I started looking for a way out of the game business. I’ll continue that story in my next post, since this is a good place to break this one off. I’ll wrap up by saying that the game in question did ship, although less than 3000 copies were delivered, and the movie-studio-interactive company in question folded up not long after that.

 Posted by at 11:30 AM