1. State of the Docs, May 9th, 2012

    • by Janet Swisher • Docs, MDN • No comments yet

    By rights, today’s edition of “State of the Docs” should be a little light, since it has been only a week and a half since a very productive documentation sprint. But our amazing documentation contributors collectively do not rest, and so there is still lots to mention.

    Outside the usual categories of docs, Tom Lowenthal created a page of privacy policy guidelines, with help from Jishnu Menon, along with a privacy policy template that you can fork on Github. If you missed the earlier Hacks post about privacy guidelines, check it out.

    Help needed

    Fbender added a note to the Talk page for JavaScript Functions and function scope that “conditionally defining a function throws an error in at least ES5 strict, possibly non-strict (at least soon), too, see Bug 609832 and Bug 585536. The section Conditionally defining a function should be updated to reflect those changes.” Want to make that change? Go for it!

    Web standards docs

    Mozilla technology docs

  2. MDN downtime on May 8th, 2012

    • by Janet Swisher • Demo Studio, Dev Derby, Docs, MDN • 1 comment

    Update 2012-05-08: Thanks to last-minute magic by Mozilla IT, MDN won’t be completely unavailable after all. However, it will be running on a single virtual machine rather than three physical servers, so expect worse than usual performance during the time frame described below.

    Mozilla Developer Network will be down for maintenance and completely unavailable for approximate eight hours on Tuesday, May 8th, 2012, starting at 15:00 UTC (Tue 17:00 CET, Tue 11:00 US-EDT, Tue 8:00 US-PDT). It should be back online by 00:00 UTC on Wednesday May 9th (Wed 02:00 CET, Tue 20:00 US-EDT, Tue 17:00 US-PDT).

    During this time, the site will not be available for viewing or editing, so please make sure to save all your edits and be prepared in advance — maybe go outside and get some fresh air — MDN will be back before you know it.

    Meanwhile, here are some alternative resources:

    Open Web standards:

    Mozilla stuff:

    • Mozilla wiki has all kinds of information related to the Mozilla project

  3. MDN First steps

    • by Janet Swisher • Docs, MDN • 4 comments

    This is a guest post by Jérémie Patonnier. This article was originally published in French. For two years now, Jérémie has been an active contributor to MDN. He organizes short doc sprints each Wednesday evening at the Mozilla Paris office. During those events, people ask a lot of questions about MDN and how to contribute. Here are the most common questions with the hope that they will help you to understand how to get involved with MDN.

    What is MDN?

    Please, don’t laugh, you have no idea how many times I have heard this.

    To get straight to the point, MDN is the Mozilla Developer Network. It’s a web site centralizing almost all the documentation about Mozilla products. Basically this site hosts three kind of resources:

    • Articles and links to external resources to learn how to use web technologies
    • Demos of cutting edge Web technologies available in modern Web browsers (Those demos come from the monthly Dev Derby contest organized by John Karahalis)
    • Reference documentation (API, elements, attributes, properties) for Mozilla technologies and more important, reference documentation for all open Web technologies (HTML, CSS, JavaScript, SVG, WebGL, etc.)

    The last part, the open Web documentation, is the most important (in terms of volume as well as quality) and the one where Mozilla currently puts its biggest effort. One thing to mention is the fact that this documentation is browser agnostic, with compatibility tables and implementation notes for all browsers, not just Firefox.

    Even if this documentation can be considered as one of the best currently available on the Web, it’s far from complete, and you are more than welcome to help with filling the gaps ;)

    Is it difficult to contribute?

    Not at all, on the contrary, it’s amazingly simple. I even think it is the easiest way to contribute to Mozilla (there is no need to deal with Bugzilla :-P)

    Actually, to contribute to MDN, you need two things:

    • The will to contribute
    • A user account on MDN

    And that’s all.

    The hardest things to do is to find the “Sign in” button in the upper right corner of the site, stuck between the search field and the ugly white Mozilla tab‚ — yeah, yeah, yeah not really the best place. Once you click it, you are prompted for an e-mail address and a password (MDN uses Mozilla Persona/BrowserID). After that, on the next page, you just have to provide a “user name” to identify your contributions on MDN and voilà, you are ready to contribute.

    For its part, contributing is also really simple. Basically, MDN is 80% a wiki. So, on each page of the wiki, you’ll find an “Edit” button (in the upper right corner). Click it to load the page content into a WYSIWYG editor (don’t worry, if you want to be hardcore, you can switch to raw HTML editing). Make all the changes you want and save them (by clicking on the “Save” button on the upper left corner). Congratulations, you’ve made your first contribution to MDN and Mozilla: no stupid publication process, no delay, no review (of course, you can ask for it, but it’s not required) — too easy :)

    What can I do, where do I start?

    The short answer is “whatever and wherever you want”. Unfortunately, experience has shown me that it’s not the answer expected by newcomers.

    Basically, you can do two things on MDN:

    • Submit demos to the Dev Derby demos monthly contest, which is pretty cool if you are a developer.
    • Contribute to the documentation if you feel you have the heart of a writer.

    Contributing to the documentation can be done in several ways, depending on the time and the will you have to get involved:

    • Writing new articles
      It’s the most time consuming contribution. However, it’s also the most useful to the most people.
    • Localizing content
      If you are familiar with a language other than English it is a good idea to translate existing material into that language. Not everybody uses English all around the world and it’s important to make the Web accessible to anyone.
    • Writing code samples
      Explanations are good, but examples are better. Many times, a good example can make things much more understandable than five paragraphs of rubbish text. So writing code samples is one of the most useful contributions and MDN really needs more.
    • Reviewing content
      As I said before, the review process on MDN is really limited but contributors can explicitly ask for review (through a tagging system). These can be editorial reviews as well as technical reviews. (Look for NeedsTechnicalReview or NeedsEditorialReview tags on pages; remove the tag if the page is OK.) If you have a small amount of time, it’s the perfect contribution that will help a lot of people.
    • Updating compatibility tables
      MDN’s open Web documentation is becoming more browser agnostic. To achieve that goal, there are many pages on MDN with browser compatibility tables. They allow users to know which API, element, attribute, or property is available for each browser. This is amazingly useful and it only take five minutes to add some compatibility data. Without a doubt, it is the easiest and fastest way to contribute to MDN.

    One last tip. Documenting the open Web is a huge task that no one can perform alone. As a consequence, it’s a good idea to focus yourself on the topics you are interested in personally. If you want to work on a specific subject, know that MDN has “Topic Drivers” that can help you; feel free to contact them. They will be more than happy to assist you.

    To complete this, there two introductory pages on MDN that can be quite helpful:

    Conclusion

    As you can see, contributing to MDN is quite simple. If you want to know more feel free to ask your question on IRC at irc.mozilla.org on the #devmo channel or through our mailing list/Google group dev-mdc. If you want to speak to someone, the best entry points are Eric Shepherd (aka Sheppy), Janet Swisher and Jean-Yves Perrier (Teoli). Those three people are Mozilla employes dedicated to MDN so don’t worry about contacting them; they signed up for it :-P

    Long live the documentation :)

  4. Doc sprint in [insert California cliché]

    • by Janet Swisher • Docs, MDN • No comments yet

    The last weekend in April saw yet another amazingly productive documentation sprint for MDN. A group of community members gathered at the Mozilla spaces in California, while others contributed remotely. The in-person group worked on Friday in Mozilla’s Mountain View headquarters, then spent Saturday and Sunday at the Mozilla space in San Francisco.

    Here is the obligatory “OMG! Awesome view!” photo from the roof deck in San Francisco, showing just some of the doc sprinters getting in the way of the view:
    April 2012 doc sprinters

    Here are only some of the things that happened in MDN docs as a result of this weekend:

    Addendum (2012-05-02): Vikash Agrawal created a code example for the contextmenu attribute; it’s not on MDN yet, but you can see it on github.

  5. State of the Docs, April 24, 2012

    • by Janet Swisher • Docs, MDN • 1 comment

    The following is a sample of the changes to the documentation on MDN in the past four weeks. We expect a large flurry of activity during the Documentation sprint this weekend. If you’re in the Bay Area, you’re welcome to join in person for any part of the sprint, or join remotely if you’re elsewhere.

    Help needed

    A reader provided feedback that they don’t understand the domQuery example in the global Function object. It needs to be more clearly explained.

    Web standards docs

    Mozilla technology docs

    Mozilla project docs

  6. Wiki Wednesday: April 18, 2012

    • by Eric Shepherd • Docs, Wiki Wednesday • No comments yet

    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.

    Note: This Wiki Wednesday is published way off-schedule, and a little short, due to a technical problem I ran into compiling it.

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

    JavaScript

    Thanks to Berker Beksag for contributing!

    SeaMonkey

    Developing Mozilla

    Extensions

    Thanks to Neil Rashbrook for his contributions since last time!

    XUL

    XPCOM

    Thanks again to Neil Rashbrook for his help!

    Interfaces

    Thanks (yet again!) to Neil Rashbrook for his contributions.

    Plugins

    CSS

    Thanks to brianloveswords!

  7. State of the Docs, March 30, 2012

    • by Janet Swisher • Docs, MDN • 2 comments

    This post got stuck in Drafts without getting published. Publishing now for the record.

    Tristan Nitot wrote a blog post describing how MDN does documentation the Mozilla way. It also gives a good summary of ways that you can help out.

    Upcoming events

    Plans are proceeding for the next MDN documentation sprint, April 27 to 29. The first day (Friday) will be the Mozilla office in Mountain View, California, and the weekend days will be in the San Francisco office. If you’re in the San Francisco Bay Area, and you’d like to join us on any of those days, you’re definitely welcome. Just contact me to let me know. If you’re located elsewhere, you’re welcome to join us remotely.

    Work is proceeding apace on Kuma, the new wiki platform that our splendid WebDev team is creating for MDN. We will be holding a test day on Friday, April 20, to bang on it on a staging server. If you’re a regular writer, editor, or localizer on MDN, we’d appreciate your help. Details about that event are forthcoming.

    Doc updates

    Here is a sampling of doc changes that have been made in the past couple of weeks.

    Web standards docs

    Mozilla technology docs

    Mozilla project docs

  8. State of the Docs, March 16, 2012

    • by Janet Swisher • Docs, MDN • No comments yet

    Documentation activity on MDN continues apace, with lots of work in the French localization, and a focus on CSS docs.

    Web standards docs

    Mozilla technology docs

    Mozilla project docs

  9. Helping with the MDN: what about linking to us?

    • by Jean-Yves Perrier • Docs • 14 comments

    We are working toward writing the best documentation about the Open Web. That’s a huge task but, day by day, our docs improve. Javascript is already considered an excellent resource, our CSS reference is now in pretty good shape, and a lot of work goes into our HTML, SVG and MathML documentation.

    Our Open Web documentation is aimed at Web developers: we want it to be useful for you. To achieve this, we follow several principles:

    • The MDN Open Web documentation must be browser-agnostic. As a Web developer, you are writing Web sites for all. You aren’t designing for a specific browser. Gecko-only documentation would be next to useless. That’s why we started about one year ago the work on making our documentation independent of the browser. We are far from being finished but huge progress has been made.
    • Our documentation must be practical. We are documenting today’s Web, not the one of yesterday or tomorrow. We base our articles on what the standard says, whether it’s complete or still a work in progress, and we point out the differences in implementation, if any.
    • Our documentation is tailored for developers of different levels. We propose tutorials for beginners, more descriptive articles for intermediate users and reference articles for seasoned developers.
    • We keep the documentation up-to-date. That’s one of our most challenging goals: outdated articles are useless. So we follow standards development daily, as well as implementation improvements. With the fast release cycles adopted by several browser vendors, standards support improves quickly, but also our amount of work. (We are happy with that!)

    Thanks to the hard work based on these principles, we see a steady increase in number of readers. For us, that’s the best reward.

    Helping us

    We regularly get questions about how you can help us. Writing new content (during a doc sprint or any other time), correcting typos, writing examples or translating articles are great ways to improve the documentation. But not everybody has the time or the knowledge.

    You can also help us with link love: Link to us from your blogs, both in-context and in the sidebar mention. This will let us get more attention, attract more editors and will help us reach our goal to provide accurate and complete documentation about the Open Web.

    To help you, we have now written a small linking guide which gives you hints and information about how to link to MDN in a pertinent way for your readers.

    So, don’t hesitate to link to our technology entry pages (like the CSS page) or to very specific pages. But don’t forget the basic rule: you are adding links for your users, the links you choose should help them quickly find accurate information. Because your readers are the important people, not us, not you.

    One way to make this into an easy habit: each time you write a blog post about an Open Web technology, take five minutes to consider if adding one or the other link to the MDN would improve your article. If it does, please add those links!

    That way, together, we will be able to improve the Open Web documentation out there. Thank you very much for your support.

  10. State of the docs, March 2, 2012

    • by Janet Swisher • Docs, MDN • 2 comments

    To organize and prioritize documentation work on Mozilla Developer Network, we are setting up a system for topic drivers. The person who is the driver for each topic area will prioritize the work for that subject and help ensure that things get written when appropriate. If you’re interested in driving the docs for a particular area, speak up on the dev-mdc mailing list, or in the #devmo channel on irc.mozilla.org. If you have questions about the docs for a particular topic area, seek out that topic’s driver in IRC, e-mail, or Twitter (or ask the community in general if you can’t find that person).

    Here’s a sampling of the activity of our splendid documentation community over the past couple of weeks.

    Web standards docs

    Mozilla technology docs

    Mozilla project docs