The Future of MDN: A Focus on Web Docs

MDN
#1

Hi all,

Last week VisionMobile released its Developer Programs Benchmarking report. A survey of more than 21,000 developers. Among the results was how „documentation and sample code are consistently listed as the single most important feature of any developer program“.
The report confirmed what we knew about MDN’s success already: "The top reference for documentation and sample code is Mozilla, who jumps up from the fourth spot in the overall satisfaction ranking to a clear leading positioning on this particular attribute. Its composite score on documentation is 85: the highest score of any vendor across any feature in our analysis.“ That’s testament to the great work the MDN team has done over the last few years.

Building MDN into a world class repository of high quality Web documentation is, truly one of the most valuable things Mozilla has done for Web developers. Now we’re looking to double-down on that work, and solidify MDN as the single best resource for Web docs. To support that effort, we’re starting some updates to the MDN brand and website.

Our first communication about our brand update is live now. This post is to let the bigger MDN user and contributor community know that we are updating our branding and why we are changing it to MDN Web Docs. It will also be the post we reference when we ask people to sign up as beta users and give us feedback on the upcoming new design.

We’re incredibly excited to make MDN officially about Web docs, and to make it more comprehensive and easier to use and learn from for all of the web developers who have come to love it as a resource.

Thanks!
Kadir

9 Likes
#2

I’m not sure I understand this post correctly. What exactly is changing? The focus? The branding to just include “Web Docs”? The whole thing to focus on Web Docs and remove Gecko doc somewhere else?

#3

Here’s a link to the blog post:

https://blog.mozilla.org/opendesign/future-mdn-focus-web-docs/

It goes into more detail about what will change in the next few months, and what we’re still discussing.

#4

So is the product documentation going to move to a different domain or is it just changes to how the site search works?

#5

Yes, the product docs will be moved to different domains, depending on what makes sense in each case. For example, the Fx build docs might move to their own domain completely, the devtools docs look like they might move to github, from conversations I’ve seen, and other smaller projects might just have their docs attached to the codebase.

Our dear friend Jean-Yves Perrier is in charge of figuring out what should happen to all of the non-web stuff.

Chris Mills
MDN content lead || Mozilla
developer.mozilla.org || MDN
cmills@mozilla.com || @chrisdavidmills

1 Like
#6

Sorry, I forgot to add the link, and thanks for providing it, John.

Trevor, no product documentation is moving off of MDN as a result of this, but as Chris said there will be support and guidance for projects that want to move off of MDN, because it makes sense for them.

#7

That’s sad because having them spread across the web properties will mean that they both will be much harder to find and much harder to edit. Just like they wouldn’t really exist any more. It was cool that MDN was the one stop shop for everything documentation at Mozilla. Well, nothing good lasts, I guess.

1 Like
#8

The feedback I heard a lot from Firefox engineering is that Mozilla docs on MDN are hard to find, outdated and many engineers don’t like editing a wiki (especially not a wiki with a WYSIWYG editor). See Firefox Source Documentation Versus MDN which outlines the dilemma of in-tree vs MDN docs/contribution.
Given there hasn’t been a substantial amount contributions to Mozilla docs on MDN and the MDN staff writers can’t handle updating docs for all teams, I think it is a good a idea to put the responsibility for internal documentation back to the engineering teams and let them decide how to do docs best. They are the ones having to write and maintain them.

The “one stop shop” isn’t true anymore anyway. MDN hasn’t been the choice for many internal Firefox engineering projects and platform modules (see here, or on github, or even on wikimo). I think now that MDN has made a clear statement, there is actually an opportunity for platform people to come together (with us) and to think about solutions that work could work across teams and how to provide modern docs.

All this said, I don’t know if Mozilla docs will be spread across many domains. We will engage with the teams and I’ve heard from a few MDN Tech Writers that they are happy to help consulting and advising on new doc home(s) for Mozilla docs. I am happy to help there, too. Hopefully our engineering culture with regards to documentation will change a bit. :slight_smile:

1 Like
#9

Aside from all that I want to reiterate: no project is being asked to leave MDN. All we want to do is make sure that web developers are not confused when they stumble upon docs that are not meant for them, but for people working on Mozilla products.

#10

Well, as I’m retreating from the last bits of Mozilla-specific development stuff anyhow (esp. now as real themes are discontinued), I personally only need MDN for the web docs.
I just feel bad for those that still want to contribute code to Mozilla itself (as hard as that is nowadays - keeping pace with MoCo is almost impossible for a volunteer) or build on the work done there (though building on Mozilla’s own code has been pretty much discouraged as well anyhow, so many no docs needed there any more).

#11

"The top reference for documentation and sample code is Mozilla, who jumps up from the fourth spot in the overall satisfaction ranking to a clear leading positioning on this particular attribute. Its composite score on documentation is 85: the highest score of any vendor across any feature in our analysis.“ That’s testament to the great work the MDN team has done over the last few years.

:thumbsup: This is great and well-deserved praise and recognition for the MDN team! VisionMobile is broad, no-nonsense market research and scoring the top spot is quite an achievement.

Great work MDN team!

3 Likes
#12

I just received an email invite for the new beta, but when I login to MDN I can’t tell any difference to when I’m not logged in.

#13

Hi Jovan,

The changes will start showing up over the next few days. We wanted get the email out in advance of the changes, so people wouldn’t be surprised when things suddenly looked different.

Janet