Mozilla

Helping with the MDN: what about linking to us?

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.

14 comments

Comments are now closed.

  1. Jay wrote on March 15th, 2012 at 01:27:

    yes, I dont done this.

    I have a banner in the right pane of my blog(http://The4thDimension.net/) pointing to the documentation at Mozilla.

    1. Jean-Yves Perrier wrote on March 15th, 2012 at 03:50:

      Cool. Thank you.

  2. Joris wrote on March 15th, 2012 at 03:38:

    MDN has always felt mozilla specific for me (I have been using MDN for a while). It’s great to see more and more improvement in this aspect.

    1. Jean-Yves Perrier wrote on March 15th, 2012 at 03:49:

      Yes, but there are still articles with a clear bias. But we try to fix them little by little, even if sometimes it is difficult to find reliable information about what other engine do really support.

  3. Paul wrote on March 15th, 2012 at 04:09:

    Just want to say a huge thank you for doing this. The docs have been extremely helpful to me (to the degree that I’ve set up a system-level shortcut for firing up MDN whenever I have a qn) and it’s awesome that they’re being expanded to be fully browser-agnostic.

    High five for you guys! :D

  4. Dave wrote on March 15th, 2012 at 04:25:

    Love the MDN docs. Clean, easy to read, and useful examples. Really glad you guys decided to take it in a browser-agnostic direction. The competition should be taking notes because this is a prime example of how you gain mind-share amongst the open web community.

  5. Max wrote on March 16th, 2012 at 10:49:

    Supercool. I’ve had a shortcut to “https://developer.mozilla.org/en-US/search?q=%s” mapped to the “mdn” keyword for some time now. Great to see even more commitment to the docs.

  6. Jeff wrote on March 20th, 2012 at 05:32:

    MDN docs are good but I have always assumed they are Mozilla specific. When your pages come up a search, I often skip over them if I am looking for something broader. Well, now that I’ve read this blog, I’m been educated, but what about everyone else?

    Seriously consider changing the name. I don’t have any brilliant ideas for a new one, but as a general direction, something like “The Universal Web Reference From the Mozilla Developer Network” melds the idea of browser-agnostic but retains the Mozilla branding.

  7. Jeff wrote on March 20th, 2012 at 05:35:

    The MDN docs are good, but I have always assumed they are Mozilla specific. When your pages come up in a search, I often skip over them if I am looking for something broader. Well, now that I’ve read this blog, I’ve been educated, but what about everyone else?

    Seriously consider changing the name of the site. I don’t have any brilliant ideas for a new one, but as a general direction, something like “The Universal Web Reference / from the Mozilla Developer Network” melds the idea of browser-agnostic with the Mozilla branding.

  8. James Cox wrote on March 20th, 2012 at 07:42:

    It’d be great if your search engine was a little better, and you submitted better site maps to google – i don’t know why w3schools consistently beats you on results.

    1. Jean-Yves Perrier wrote on March 20th, 2012 at 10:36:

      The search engine could have some love, that’s correct.
      For being before w3schools, a sitemap won’t be enough. We need to better the content (better titles for example), to better the form (speed, speed, speed!) and mainly to get a lot more links: they are collecting them since years and are far ahead of us. Note that for recent CSS features, we are usually better positioned than them, because we started building popularity for these pages more or less at the same time.

      That’s why linking to us will help a lot.

      1. Roland Frank wrote on March 21st, 2012 at 16:12:

        Given meaningful titles – I am up to provide a lookup interface based on title words and predictive completion. Something similar – yet outdated – for reference: http://taipu.de/ida.htm gives easy access to wiki pages with minimal user interaction.

  9. Hitesh Khandelwal wrote on March 20th, 2012 at 10:28:

    I think MDN would be awesome if users have the ability to add comments on the wiki pages. PHP and MySql documentations are great because of them.

    1. Jean-Yves Perrier wrote on March 20th, 2012 at 10:41:

      That’s something we are considering to do. It could help getting feedback, but the best would be to have the good ideas integrated in the article, but that would make the comments redundant (and we should remove them, which may upset the commenter).

      It is not that easy (except if you do like php/mysql where comments stay forever and articles aren’t updated)

Comments are closed for this article.