sheppy

Writer. Programmer. Geek.

 

Here are today’s Wiki Wednesday articles! If you know about these topics, please try to find a few minutes to look over these articles that are marked as needing technical intervention and see if you can fix them up. You can do so either by logging into the wiki and editing the articles directly, or by emailing your notes, sample code, or feedback to mdnwiki@mozilla.org.

Contributors to Wiki Wednesday will get recognition in the next Wiki Wednesday announcement. Thanks in advance for your help!

JavaScript

SpiderMonkey

Developing Mozilla

Extensions

XUL

XPCOM

Interfaces

Thanks to Neil Rashbrook for contributing!

Plugins

CSS

Thanks to leeli and Panagiotis Tsalaportas for their contributions!

SVG

HTML

Thanks to Panagiotis Tsalaportas and Neil Rashbrook for their contributions since last time.

DOM

Thanks to Matt N. for his contribution to the DOM documentation.

 

Last week, the writing team took a look at how documentation work is progressing, and the enormous amount of it coming up in the months ahead, and we realized that our old method of prioritizing writing work doesn’t do the job anymore. In the past, we prioritized work first by which Firefox release it was due to be shipped in, then by topic area.

That simply doesn’t work anymore. Between the rapid release schedule and the fact that we often start promoting new technologies while they’re in Nightly or Aurora builds, we can’t focus on one release at a time. So we’ve decided that going forward, we’re going to prioritize documentation based on the importance or “interestingness” of the topic, regardless of which Firefox release it’s expected to ship in.

This means that going forward, we’re much more likely to ship Firefox releases that don’t yet have complete developer documentation, but it also means that we’re more likely to have all the most important and broadly interesting topics written up earlier in the development process. Of course, we’ve already started to have trouble getting documentation for a release “finished” in time anyway, so this isn’t a big surprise. But by accepting it and embracing the hugeness of the task ahead, we can make better decisions about what to write and when.

Hopefully the Mozilla community will be able to step in and fill the gaps that get left behind as we move forward. There will be lots of great opportunities to contribute to MDN. I look forward to seeing what you can do to help!

 

I apologize for liking it.

 

Here are today’s Wiki Wednesday articles! If you know about these topics, please try to find a few minutes to look over these articles that are marked as needing technical intervention and see if you can fix them up. You can do so either by logging into the wiki and editing the articles directly, or by emailing your notes, sample code, or feedback to mdnwiki@mozilla.org.

Contributors to Wiki Wednesday will get recognition in the next Wiki Wednesday announcement. Thanks in advance for your help!

JavaScript

SpiderMonkey

Developing Mozilla

Extensions

XUL

XPCOM

Interfaces

Plugins

CSS

SVG

HTML

DOM

 

As you’re probably aware, we’ve had a series of problems with the wiki lately. I’d like to share a status report as to what those are and where we stand.

Failing wiki extensions

There’s an issue that’s causing extensions that add features to the wiki to fail to start up. This is a problem caused by a bug in the wiki software that’s not properly handling the scenario in which multiple hosts are restarted at the same time. Due to a lack of proper mutual exclusion during wiki startup, the launch of extensions can fail fairly spectacularly, resulting in the loss of the configuration of the extensions, so that future attempts to start them are guaranteed to fail.

This didn’t happen on every restart (oh, the joy of mutual exclusion bugs), but happened pretty often. Since the wiki periodically restarts itself automatically to clean up cruftiness, the result was that this bug would randomly crop up fairly frequently.

Late last week, MindTouch’s support team gave us a script that detects when this has happened and repairs the lost configuration and restarts the extensions. This was tested over the weekend on three of our most commonly-used extensions, and seems to have worked very well. They’ll be adding the rest of our extensions into the mix tomorrow.

That’s a short-term, hacky, workaround for the problem.

MindTouch’s engineers are working on a patch that will correct the underlying bug. They’ve implemented the fix on their trunk codebase, and are testing it there now. It’s a substantial revision to how extensions are loaded, and they want to get it thoroughly tested. Once they’re sure the patch works, they’ll backport it to the release we’re running and test it there. Then, finally, we’ll get it installed, and we should be in good shape.

This situation is being tracked in bug 715341 if you’d like to follow along.

The Great DOM Reference Kerfluffle

While experimenting with some ideas for the DOM Reference, Jean-Yves inadvertently initiated a move of the entire DOM Reference to a different part of the wiki. That was bad enough, but could have been easily fixed. Unfortunately, the site crashed partway through the move, resulting in things being left in a state where it wasn’t a simple “move the subtree back where it belongs” operation. Instead, he had to manually move every page back where it belonged one at a time. This took several days, but is now finished. If you notice any issues with the DOM Reference, please let us know!

 

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.

 

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.

 

Here are today’s Wiki Wednesday articles! If you know about these topics, please try to find a few minutes to look over these articles that are marked as needing technical intervention and see if you can fix them up. You can do so either by logging into the wiki and editing the articles directly, or by emailing your notes, sample code, or feedback to mdnwiki@mozilla.org.

Contributors to Wiki Wednesday will get recognition in the next Wiki Wednesday announcement. Thanks in advance for your help!

JavaScript

Thanks to David Bruant, -TNO-, and xkizer for their contributions the last couple of weeks.

SpiderMonkey

Developing Mozilla

Extensions

XUL

XPCOM

Thanks to Neil Rashbrook for his contributions!

Interfaces

Plugins

CSS

Thanks to McGurk and cgack for their contributions to CSS documentation!

SVG

HTML

Thanks to Jens.B and tw2113 for their contributions since last time.

DOM

Thanks to cgack for contributing!

 

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.

 

Next up in my cavalcade of influences that led me to become the technical writer I am today: Morgan Freeman. Yes, that Morgan Freeman. As I mentioned in my previous post about my influences, I watched “The Electric Company” a lot as a kid. A very young Morgan Freeman, playing the role of Easy Reader, made reading really cool. I learned a lot from that show, and although he was certainly not the only actor (and Easy Reader not the only character) to impact my love of reading and of words, he was the most impactful and memorable.

Being taught by someone that cool that reading wasn’t just something you do because you have to, but because you want to, was critical at that age. So… thanks, Mr. Freeman!

© 2012 Bit Stampede Suffusion theme by Sayontan Sinha