MDN Web Docs: Editorial strategy and community participation

We’ve made a lot of progress on moving forward with MDN Web Docs in the last couple of months, and we wanted to share where we are headed in the short- to mid-term, starting with our editorial strategy and renewed efforts around community participation.

New editorial strategy

Our updated editorial strategy has two main parts: the creation of content pillars and an editorial calendar.

The MDN writers’ team has always been responsible for keeping the MDN web platform reference documentation up-to-date, including key areas such as HTML, CSS, JavaScript, and Web APIs. We are breaking these key areas up into “content pillars”, which we will work on in turn to make sure that the significant new web platform updates are documented each month.

Note: This also means that we can start publishing our Firefox developer release notes again, so you can keep abreast of what we’re supporting in each new version, as well as Mozilla Hacks posts to give you further insights into what we are up to in Firefox engineering.

We will also be creating and maintaining an editorial calendar in association with our partners on the Product Advisory Board — and the rest of the community that has input to provide — which will help us prioritize general improvements to MDN documentation going forward. For example, we’d love to create more complete documentation on important web platform-related topics such as accessibility, performance, and security.

MDN will work with domain experts to help us update these docs, as well as enlist help from you and the rest of our community — which is what we want to talk about for the rest of this post.

Community call for participation

There are many day-to-day tasks that need to be done on MDN, including moderating content, answering queries on the Discourse forums, and helping to fix user-submitted content bugs. We’d love you to help us out with these tasks.

To this end, we’ve rewritten our Contributing to MDN pages so that it is simpler to find instructions on how to perform specific atomic tasks that will help burn down MDN backlogs. The main tasks we need help with at the moment are:

We hope these changes will help revitalize the MDN community into an even more welcoming, inclusive place where anyone can feel comfortable coming and getting help with documentation, or with learning new technologies or tools.

If you want to talk to us, ask questions, and find out more, join the discussion on the MDN Web Docs chat room on Matrix. We are looking forward to talking to you.

Other interesting developments

There are some other interesting projects that the MDN team is working hard on right now, and will provide deeper dives into with future blog posts. We’ll keep it brief here.

Platform evolution — MDN content moves to GitHub

For quite some time now, the MDN developer team has been planning a radical platform change, and we are ready to start sharing details of it. In short, we are updating the platform to move from a Wiki approach with the content in a MySQL database, to a JAMStack approach with the content being hosted in a Git repository (codename: Project Yari).

This will not affect end users at all, but the MDN developer team and our content contributors will see many benefits including a better contribution workflow (via Github), better ways in which we can work with our community, and a simplified, easier-to-maintain platform architecture. We will talk more about this in the next blog post!

Web DNA 2020

The 2019 Web Developer Needs Assessment (Web DNA) is a ground-breaking piece of research that has already helped to shape the future of the web platform, with input from more than 28,000 web developers’ helping to identify the top pain points with developing for the web.

The Web DNA will be run again in 2020, in partnership with Google, Microsoft, and several other stakeholders providing input into the form of the questions for this year. We launched the survey on October 12, and this year’s report is due out before the end of the year.

About Chris Mills

Chris Mills is a senior tech writer at Mozilla, where he writes docs and demos about open web apps, HTML/CSS/JavaScript, A11y, WebAssembly, and more. He loves tinkering around with web technologies, and gives occasional tech talks at conferences and universities. He used to work for Opera and W3C, and enjoys playing heavy metal drums and drinking good beer. He lives near Manchester, UK, with his good lady and three beautiful children.

More articles by Chris Mills…


4 comments

  1. Mark

    I’m pleased that work is continuing on platform improvements. Question: any chance of bringing back the CodePen/JSFiddle buttons below live samples? I thought those were really useful.

    I’d also love to see the CSS examples on top of every page get upgraded, so that we can see all the code–sometimes a line or two of CSS isn’t enough to fully understand what’s going on.

    October 22nd, 2020 at 11:37

    1. Chris Mills

      Thanks for the feedback Mark. We are starting with a small featureset on the new platform, and then slowly building it up. Both of your thoughts here are definitely worthy of consideration.

      October 23rd, 2020 at 01:58

  2. Clark

    Exciting stuff!
    Coincidentally I was reading up on MDX (Markdown-X) yesterday and just wanted to gently poke you in the ribs and say: “Hey, maybe that’s a good fit for your documentation once you’ve moved to Github”.

    I would love to contribute if the workflow is a good one, such as with Markdown and Github.

    Stay strong!

    October 22nd, 2020 at 23:24

  3. Chris Mills

    Hi Clark! As in, https://pypi.org/project/django-markdownx/? Looks really interesting, although the current plan would not involve using Django for our content editing. But never say never, at least not for now.

    Initially the content will be raw HTML inside GitHub, but we are intending to move it over to some kind of markdown flavor in the future (possibly our own custom MDN markdown).

    October 23rd, 2020 at 02:00

Comments are closed for this article.