Articles for October 2010

This is a guest blog post by Chris Williams, the curator of JSConf. We are proud to support the PromoteJS campaign and hope everyone will join us to improve JS docs and make the MDN a better place for all web developers.

PromoteJS – A Worldwide Call For Improving JS Documentation Visibility

JS is not a toy language. That reality is just now reaching most developers and their first impression of JS is absolutely abysmal. Do you know what shows up when you search for “JavaScript“? The search engine results page is topped by a Wikipedia article which is shortly followed by the page for downloading Java. This is probably why so many people still unfortunately believe there is a connection between JavaScript and Java. The results for other common search terms like “Learn JS” and “JS Array” is equally as bad if not worse.

This is the first impression of JS by the general masses who are coming to this language and once you see this, you can see why people consider it a “toy language” and understand how so much bad code and disdain can exist for JS. We have hidden the better tutorials, learnings, and documentations away from ourselves AND more to the point, those trying to learn this language. New entrants struggle to learn JS, but eventually just adopt what they know from PHP, Java, Perl, Python and Ruby to a close approximation of runnable code that suffices. They then publish it back out, proud of what they have done, and continue to perpetuate this plague of improper JS coding.

We have failed our fellow designers AND developers in this sense. We have made it almost impossible to learn proper JS, a language with both beauty and warts. Some will say it is not our fault, that browser vendors should provide the API documentation for the implementation or that the standards committee should publish and market it. I am calling bullshit on that. I say that it is up to us to invite, welcome, and most importantly properly educate people looking to learn JS. We, the best and brightest of the field, have an obligation to help those who are trying to learn and understand the complexities of the language. We are the ones that benefit from it most, since those now entering the language will be either extending, morphing, or taking over the very projects we are just now starting. Regardless of library, framework, and even language — if everyone knows how to program proper JS a little better, we all win. Period.

So I challenge you to put down your library or framework preferences and write about some interesting facet about the JS language. Describe how you find the attributes on an object, what the difference between an object and an array is (and how to tell the two a part), anything and everything. If you seek fame and click traffic, write about the entry level stuff. If you seek respect and deep dialogs, write about the difference between implementations and convey the wisdom of when to favor one method over the other. If writing is too time consuming or your muse escapes you, I am announcing today a new campaign, PromoteJS. Through organic guerrilla SEO we can change how search engines present answers to common queries about our language and in doing so improve the visibility of proper educational resources. Our initial target for PromoteJS is to make the proper MDN documentation the first result for standard new JS developer queries.

In order to track our efforts, we have also released Are We First Yet which is a node.js application that tracks the search engine page rank for each of the target terms. Tracking is done on a day-over-day basis so that everyone can see the progress we have made and, if so desired to help the cause, write articles targeting the keywords. With these two efforts, we hope to enabled not just the JS community, but all developers, to improve the visibility of proper documentation. In the few days since unveiling this effort at JSConf EU, there have been millions of page views for the PromoteJS site and the button has spread like wildfire throughout the community. We have already drastically improved the rankings for key terms like “Learn JS”, “Learn JavaScript”, and “JS Documentation”, but we need your help to continue to improve all the rankings.

We need to be the voice of education for our community. We need to promote the proper way of doing things, instead of just ignoring those that don’t “get it” or watering things down. We need to commit to educating our fellow developers on JS, the language, and in doing so it helps all of our frameworks, libraries, meetups, and conferences. PromoteJS is a step in that direction, but by no means the end of the story, be sure to check the site frequently as we continue to add new ways to help improve documentation visibility and the documentation itself.

Chris Williams
Curator, JSConf

For the past three days, a small group of Mozillians met in Paris and, instead of enjoying the beautiful warm weather, insanely stayed inside and wrote documentation on web standards for the Mozilla Developer Network. We worked in the Mozilla Paris office on Saturday and Sunday, and then on Monday moved to La Cantine, around the corner, so the staff could use the office. We also enjoyed some long, relaxed French lunches and dinners and saw a bit of the city, but mostly we wrote docs.

“Action” shot of MDN doc sprint contributors (L-R: Jean-Yves Perrier, Florian Scholz, Eric Shepherd, Paul Rouget, Sebastian Perez Vasseur, Janet Swisher. Missing: David Bruant)

Here’s what we accomplished:

• David Bruant
  • expanded, updated, and enhanced JavaScript strict mode;
  • expanded and added examples to Object.defineProperty;
  • added a section on Enumerating all properties of an object to the topic on working with JavaScript objects;
  • reviewed and corrected Object method topics.
• Sebastian Perez Vasseur
  • wrote Introducing the Audio API extension, Visualizing Audio Spectrum, Creating a Web based tone generator, and Displaying the Mozilla logo with the Audio Samples;
  • wrote SVG animation with SMIL;
  • documented NotifyAudioAvailableEvent;
  • created a thematic classification for HTML5 topics;
  • created a banner for HTML5 topics, and added it to appropriate pages;
  • added Mozilla-specific properties to HTMLMediaElement;
• Florian Scholz (aka Elchi3)
  • documented 21 out of 30 MathML elements;
  • restructured the SVG element reference.
• Jean-Yves Perrier (aka teoli)
  • wrote an introduction to HTTP;
  • created a page to collect topics on HTTP headers;
  • created a page for HTTP response codes;
  • started documenting HTML5 constraint validation.
• Eric Shepherd (aka Sheppy)
  • wrote CSP overview, Introducing Content Security Policy, Using Content Security Policy, Default CSP restrictions, CSP policy directives, and Using CSP violation reports;
  • created scripts to generate tables-of-contents both alphabetically and by-category automatically;
  • documented -moz-image-rect and -moz-calc;
  • improved topics on CSS transitions and -moz-transition based on feedback from David Baron;
  • cleaned up Firefox 4 for developers.
• Janet Swisher
  • edited CSS Getting started tutorial, part I, and added solutions to the exercises and links to properties in the CSS Reference;
  • wrote this blog post, which is documentation of the sprint :-)
• Paul Rouget was a fantastic “localhost” and technical reviewer. Expect to see more awesome stuff from him in the coming days and weeks.

It takes a special kind of person to set aside a weekend when they could be having other kinds of fun or maintaining a personal life, to devote to writing technical documentation. The documentation that was written this weekend moves MDN further towards the goal of being a comprehensive, usable, and accurate resource for everyone developing for the Open Web. Many thanks once again to the volunteer contributors, as well as to the Mozilla Paris staff who welcomed us and facilitated our visit.

For a final taste of life in France, we will now attempt to travel during a French transit strike.

The weekend of October 9 to 11, we are holding our first ever documentation sprint, at the Mozilla Paris office. A documentation sprint is like a code sprint or hackfest, except that the focus is on writing docs instead of on writing code. In this case, the specific focus is documentation on the Mozilla Developer Network related to open web standards and how to use them. That includes HTML5, CSS3, MathML, next-generation JavaScript APIs, and so on.

This event is inspired by the “book sprints” pioneered by our friends at the FLOSS Manuals project, but instead of writing a book in three days (yes, it can be done and has been done), we’re going to write a whole bunch of topics for MDN in three days.

If you know a thing or two about open web standards and you enjoy writing documentation, I invite you to participate, either remotely or in person if you’ll be in Paris. E-mail me at jswisher at mozilla dot com with “doc sprint” in the subject, and let me know what you’re interested in writing about (and where you’re located). If you’re not sure exactly what to write about, I can suggest some ideas. It’s OK if you can’t participate for all three days, but please be willing to contribute some significant time and effort. Because physical space is limited, please don’t arrive in person without contacting me first. For remote contributors, we’ll use the #devmo channel on irc.mozilla.org, which is where discussion about MDN normally happens. I’ll also set up some conference calls to help keep the remote contributors in tune with the folks in the room.

Among the ideas for things to write is tutorials based on some of the wonderful demos that Paul Rouget and others have posted on this blog. That is, deconstruct a demo, and describe step-by-step how to create it. Then, at the Drumbest Festival next month in Barcelona, we’ll get feedback on any tutorials we create from festival participants in the Webcraft Toolshed. If the materials we create are on appropriate topics and of high enough quality, they might be used in the next course sessions of the Peer-to-Peer University’s School of Webcraft.

As usual for MDN, most docs will be written in English. However, if you’re more comfortable writing in French, I volunteer to attempt to translate into English. For those writing in English, we can help edit what you write, so it’s OK if you don’t write perfectly (no matter what your native language is).

I’m really looking forward to this event, and excited to see what we will accomplish to extend and enhance the documentation on MDN.