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.

View full post on Mozilla Hacks – the Web developer blog

Tagged on: , ,

7 thoughts on “Helping with the MDN: what about linking to us?

  1. Dave

    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.

  2. Paul

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

  3. Jean-Yves Perrier

    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.

  4. Joris

    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.

Leave a Reply