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.

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.

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.

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!

The first and most obvious influence is my parents. In particular, my mom. There are two ways in which she influenced my love of writing.

First, I have vague memories of her printing things like my name and having me copy them, to do things like sign holiday cards. And I always had lots of books. We have recordings of my little voice reading A Fly Went By aloud to my grandparents. “I axed him why he flew so fast…”. Good for the brain cells!

Second, and more interestingly, she would sit me in front of the TV after school and I’d watch Sesame Street, Electric Company, and, eventually, 3-2-1 Contact. Mom tells a story of how my kindergarten teacher was impressed by how I could already read and write, and asked if Mom had been teaching me. “No,” she said, “He learned that watching PBS.”

The point is, my parents encouraged me to read starting very young, before I was even in preschool, and always made sure I had lots of things to read. In fourth grade, I’d spend an afternoon plowing three Hardy Boys books, sometimes three or more in an afternoon. Those were good times, and getting an early start reading certainly helped get me where I am today!

This one little guy was fascinated with Sophie. He followed her as she moved back and forth in front of the window.

Then you had these other cuties:

I have more pictures and some video as well, but this was the best stuff. How can you not love creatures this precious?

Even more usefully, we’ve been gradually building out templates to help make it easier for you! We have a lot of templates that do things specific to Firefox, and we’re trying to either genericize those or add new ones for other browsers. WebKit has gotten special attention since our friends at Google have been contributing some great content, but we welcome folks to create templates for use when documenting support of open web features in other browsers as well.

The two templates for WebKit writers I’m going to mention today are WebKitBug and unimplemented_inline_webkit.

WebKitBug inserts a link to a bug in the WebKit bug database. This makes it easy for writers to add annotations to documentation to guide developers to information about things that are works in progress in WebKit. You use it like this: {{webkitbug(42)}}, and the result is “WebKit bug 42″, linked to the corresponding bug in the bug database.

Similarly, unimplemented_inline_webkit inserts a small, inline box with an optional link to a WebKit bug, given its bug number. If you write {{unimplemented_inline_webkit()}}, you simply get a box that says “Unimplemented”. More usefully (and preferred) is the syntax {{unimplemented_inline_webkit(42)}}, which inserts a box that says “Unimplemented (see WebKit bug 42)”, with a link to the bug.

Obviously this is just a beginning! I’d love to hear suggestions on ways we can further improve this, either by changing existing templates or by adding new ones. Feel free to follow up with comments here, or chat with me in #devmo on IRC.

Consider this, for example:

Here we see a big banner about how this method of the DOM Element object was introduced in Gecko 1.9.1. However, it’s actually a standard DOM method. This banner should go away, and the text should be updated wherever necessary to remove any Firefox-specific discussion.

In addition, the article should have our standard browser compatibility table at the bottom. This table provides information about which releases of all the major browsers introduced support for the feature.

I’ve updated this article now so it looks the way it’s supposed to, as an example of what it ought to look like.

Noting introduction of sub-features

Some features are fairly complex; for example, the HTML <input> element has evolved over time, with the addition of new attributes and new possible values for many of them. This is where adding additional rows to the browser compatibility table comes into play. Let’s look at a few rows from the compatibility table for <input>:

Here we see multiple table rows, each for a given named feature of the element being documented. In the case of Firefox, we see that type=color isn’t implemented yet, and we used {{unimplemented_inline(547004)}} to include a link to the corresponding bug. We also have the WebKitBug template for linking to WebKit bugs, and should add an unimplemented_webkit_inline or similar for creating Unimplemented badges that link to WebKit bugs, but haven’t done so yet.

Browser version-specific notes

Sometimes, you simply have to note browser-specific stuff, even in open web documentation. This should usually be done in the “Browser compatibility” section, with a subsection added for each browser that needs a note. For example, the browser compatibility section on the main WebSockets page has a subsection entitled “Gecko notes,” which covers Gecko-specific issues related to WebSockets, such as the fact that the constructor is prefixed.

If you do need to include browser-specific content in the middle of article text, try to put it in a call-out box or note box instead of just throwing it into the body text of the article.

The future

As we continue to build our Kuma, our new wiki platform for MDN documentation, we’re keeping browser agnosticism for documentation in mind. We have features planned to make it easier to call out browser differences and browser specific features, and to help readers filter the content based on their interests.

When in doubt… ask!

While updating or writing open web documentation, if you run into something that you’re not sure how to handle, please feel free to pop into #devmo on IRC, or to drop email to me, and ask for help. All of our happy, helpful documentation gnomes live to serve.

I, on the other hand, had always been rather skeptical of open source. Indeed, back in 2005, I was working quite happily at PalmSource (the company that produced the operating system for the Palm PDAs and Treo smartphones), writing developer documentation there, and my experiences with open source products had been almost universally negative.

Then, right around the time my daughter was born, I got laid off, one of the many casualties of PalmSource’s long decline and death throes. I quickly got a contract job writing game software, which turned into a full-time job, but that didn’t pan out for reasons that don’t really matter here. What does matter is that in early 2006, I was in need of a job.

Dave Miller (justdave), a long-time friend of mine, had been involved with Mozilla for years by this point, and he mentioned that they were in need of Mac programmers, so I sent along a resume, and he put in a good word for me. I was brought in and interviewed, where I followed the non-traditional course of basically saying that I thought open source was a good idea but so far had been unimpressed, and that I didn’t like Firefox because it was really ugly on the Mac.

Apparently this didn’t put off Shaver, Asa, Chris Beard, and the others I spoke to — or perhaps they were willing to overlook it once they discovered I had almost ten years of experience doing heavy-duty developer technical writing — because I wound up getting offered a tech writing job. I started on April 3, 2006, and never looked back.

I’ve enjoyed nearly everything about my time with Mozilla so far and don’t see much chance that will change in the near future. There are challenges and occasional frustrations, but the rewards have been fabulous.

I still look upon open source software with a great deal of skepticism, but I don’t automatically assume the worst anymore like I used to. If more open source projects were administrated with even half the adroitness as the Mozilla project, the technology world would be a better place.