Geekology – Page 7 – Bit Stampede

Kilimanjaro and its impact on documentation

Firefox, Geekology, MDN, Mozilla No Responses »

Apr 062012

A few days ago, Damon shared an announcement about what we’re calling the “Kilimanjaro event.” This is that point in time at which we expect our release process to have led to the ability for users to find and install Web apps easily. There’s more to it than that, so read the forum post Damon wrote and then come back. This will wait.

Done? Good.

So this is going to have something of an impact on the priorities for Mozilla’s staff documentation team. Since we’re putting an emphasis on Web apps and, by extension, open Web standards, we’re going to be increasingly focused on this area of documentation, and by extension (no pun intended) less of our attention will be directed toward add-on related documentation.

That means we’re going to need to rely more on the broader community to cover extension and other add-on related documentation work. If we don’t pull together a few folks to volunteer to work on that, it will likely fall behind significantly over the coming months, unfortunately. We will see what we can do to at least ensure the absolutely critical stuff (things that break compatibility, for instance), but beyond that, it will pretty much be up to you!

In the meantime, the staff writers will be doubling down on the Apps, BrowserID, Open Web (CSS/DOM/HTML/JavaScript), WebAPI, and probably WebRTC related documentation.

You can expect to see further blog posts on this over the coming days and weeks. It’s going to be an exciting ride!

Documenting the important stuff first

Firefox, Geekology, MDN, Mozilla No Responses »

Mar 292012

Firefox is changing fast. So is the Web, for that matter. There are so many new APIs and technologies pouring forth from the clever minds of all those engineers that the developer documentation team is struggling to keep up. Indeed, we’re slowly falling farther behind.

That means we need to sort out which documentation issues need addressing the most urgently.

What documentation is “important”?

There are basically two categories of high-priority documentation:

Very new and exciting technologies that we want to be able to make a big deal of. These need documentation so that developers can jump into them quickly and easily.
Significant changes to existing technologies that may cause problems for existing web content or Firefox add-ons.

The documentation team isn’t always the best set of people to determine which documentation issues fit into these categories. As such, we need to start recruiting others to participate in the prioritization process.

Who can help?

Those two categories of high-priority documentation I mentioned above just happen to correspond to two very different sets of people:

Evangelists and product marketing folks are ideal for flagging the priority on documentation issues that correspond to new and exciting technologies. They want to be able to promote technologies through blog posts, press releases, release notes, and so forth, and as such want to have documentation for those high-visibility technologies. Preferably before they start making a fuss about them.
Engineers and developers tend to know which changes are going to be a headache for web and add-on developers. That puts them in a perfect position to mark the priority on these documentation issues.

How do you help?

If you fit into one of these categories (or, really, even think you’d like to try to help out), you can easily help prioritize our documentation issues! We use a documentation tracker web application developed by Florian Scholz. It interfaces with Bugzilla, using the dev-doc-needed and dev-doc-complete keywords we apply to bugs that affect documentation, but adds additional features, including support for tracking bugs by Firefox release, additional note fields, and, most importantly for the purposes of this blog post, a priority field for each bug.

So here’s how you can help: go to the documentation tracker, log in (using your Bugzilla login), and peruse the list of bugs. Click the edit button at the right edge of the row for any bug you can help prioritize, and set the priority. It’s that easy; it’s a wonderful tool and we use it a lot.

What do the priorities mean?

The priority field can be set from 1 to 5. Each of these values means something fairly specific (in fact, I’m hoping Florian will update the tool to include a reminder of the meanings in each menu item in the popup for the priority). Those values are as follows:

Must be documented if possible within one week after reaching Aurora.
Must be documented if possible within one week after reaching Beta.
Must be documented if possible within one week after release.
Must be documented if possible before the next release.
Should be documented. Someday.

Yes, these values are tied to Firefox releases. However, that gives a general sense of the urgency of the item, even independently of Firefox itself.

Let’s say you’re an evangelist, and you’re looking over the list and see that a particular bug corresponds to a technology you want to blog about when the corresponding release reaches Beta. You should in that case set that bug’s priority to 2. That lets us know to put a rush on that item, but not to block any priority 1 items on it.

It’s not a guarantee!

It’s important to keep in mind that our resources are stretched pretty thin right now. We can’t guarantee that items will be documented by the time the priority requests it be done. We will, however, do our best. And, of course, you should always feel free to contribute documentation. Even a rough outline will encourage someone to come along and spruce things up!

Help us help you

The developer documentation team is here to help. We can get things done faster if you give us all the information you can about when you need something written and, if possible, how it works (or at least the name of someone we can contact to ask questions). Feel free to add that to the notes field in the doc tracker!

And, as always, feel free to contact me by email or drop into the #devmo channel on IRC with your developer documentation related questions.

Integrating real-world samples with documentation

Firefox, Geekology, MDN, Mozilla, Writing 2 Responses »

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?

Looking for a writing contractor for events documentation!

Firefox, Geekology, MDN, Mozilla, Writing 1 Response »

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!

A writer’s inspiration: The English language

Geekology, Mozilla, Writing 3 Responses »

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.

A writer’s inspiration: Doug Fulton

Geekology, Mozilla, Writing No Responses »

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.

A writer’s inspiration: The designers of that game

Geekology, Mozilla, Writing 1 Response »

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.

A writer’s inspiration: Morgan Freeman

Geekology, Mozilla, Writing No Responses »

Jan 242012

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!

A writer’s inspiration: Mom and Dad

Geekology, Mozilla, Writing No Responses »

Jan 232012

This morning I was following this obscure train of thought stream that wandered randomly from one thing to another, when I started thinking about the people, things, and events that influenced me to eventually become a technical writer. Then it occurred to me this could make for an interesting set of blog posts, so here we are!

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 through 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!

I finally visted the Knoxville Zoo!

Firefox, Geekology, Mozilla, Personal 1 Response »

Dec 032011

I live less than 30 minutes away from the Knoxville Zoo, which is home to one of the pre-eminent red panda breeding programs in the world. Today, finally, I took my daughter to see the new red panda pavilion that hadn’t been finished yet last time we were there. It’s a beautiful facility, and you can get a first-class, front-row look at the same little beauties that the Firefox Live live stream shows.

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