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.
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.
About Jean-Yves Perrier
Jean-Yves Perrier is a Tech Writer in the Developer Engagement team. He can be followed as @teoli2003 on Twitter.