MDN feature suggestions


Coming from a wiki-background, I’d say there’s a lot MDN can learn from how Wikipedia and other MediaWiki-based wikis solved this.

When I started editing at MDN, I was very surprised how there was pretty much no one watching over my edits. On the one hand, I do enjoy the loose moderation - on Wikipedia specifically, it is way too easy to revert an edit, which makes it frustrating for new authors. It can happen that you put in a lot of effort finding sources and getting the wording right, and then another user can just revert your changes and all the work is wasted. You are not supposed to revert the revert, you have to contact them on their talk page and figure it out, at which point you lost the interest in it.

In contrast, this is unlikely to happen at MDN, but I would wish for more hand-holding at the beginning, especially when it comes to guidelines on how pages should be structured or which templates to use. I know there are some guides on this, but they are very hard to find unless you have the link to them, some of the info is outdated, and it’s just too much to read through at once, especially since a lot of it is self-explanatory and doesn’t need mentioning.

To start with, the Revision dashboard could use an overhaul. I actually enjoy looking at it from time to time to see what pages have been edited, and it is an easy way to check for spam.

My feedback:

  • It took me a while to figure out you could click on a row to see the diff. There should be a note at the top mentioning this.
  • When you change the tags (add a new tag, delete a tag), this is not shown in the diff. This is a major issue and should be fixed ASAP.
  • For some reason the filters don’t work or have a horrible performance. For example, I have no interest in the other languages, I only care about the en-us pages, yet when I want to apply a filter to set the locale, it stays at “Hang on! Updating filters…” forever and doesn’t update.

See also Recent changes on Wikipedia for comparison.

Some other feedback:

I hope that you can get the pages into a uniform format; right now every section on MDN has their own weirdness.
For example, I don’t understand why Web APIs must use Class.method() instead of Class.prototype.method() or Class#method(), which it is allowed for the JavaScript core pages. This rule only creates confusion, e.g. on MediaSource between MediaSource.isTypeSupported() and MediaSource#addSourceBuffer(). On pages like Float32Array, this rule is not being followed.

When you look at the raw source code instead of the visual editor, you’ll find many differences between the pages, e.g. some pages use a <div> instead of <p>, or they insert &nbsp; instead of spaces, or the title="" is missing from <h2> headings.
We are all developers, so it shouldn’t be hard to write a few bots to take care of maintenance like this. I’d do it myself but I don’t dare writing a bot myself and just spamming the revisions dashboard without approval.
Wikipedia solves this by having their own Wiki markup. Maybe MDN could switch to either this or Markdown instead of HTML, this would make the code less verbose and prevent those small differences in code.

And finally, I hate that you outsourced the templates into the GitHub repo. For example, the SpecName template is outdated, it is missing some specs, or the URL or status may be wrong.
I took a look what it would take to set up a dev environment and create a pull request, and immediately lost interest. There’s no reason to not have the templates integrated into the site. On Wikipedia, everyone can edit templates (though obviously some of the more widely-used templates cannot be edited by anyone but you need privileges for that).

Moderation of new editors: creating a monitoring list/greylist

I’d say there’s a lot MDN can learn from how Wikipedia and other MediaWiki-based wikis solved this… I would wish for more hand-holding at the beginning…I hope that you can get the pages into a uniform format; right now every section on MDN has their own weirdness…Maybe MDN could switch to either this or Markdown instead of HTML…

There are lots of good points in here. I think it’s fair to say that if we were starting from scratch we would not make a lot of the same architectural choices that we originally made.

Unfortunately it’s hard to know how to get from here to there.

(Eric Shepherd) #3

Yeah, we’re still working on finalizing the proper structures of certain types of pages, as part of an effort to bring everything into line. It’s coming, slowly, as we’re able to make time between writing about web standards. :slight_smile:

I’m in the middle of work on an update to the wiki platform such that when you choose to create a new page, you get asked what type of page you want to add, and after clicking the “New page” button from there, you’re given an editor pre-populated with the template for the page you’re creating.

Longer term, we want to look into ways to automatically start reference pages pre-built with basic content generated by scanning WebIDL files, but that’s a much more intricate project.

Yes, it needs some work. It’s slow, and it’s a little bit flaky in places. It’s generally pretty impressive given the somewhat haphazard way it was built over time, but it could use a rebuild now that we have a better idea how it’s being used.

Agreed. That’s a good idea. You should feel free to file a bug and suggest this.

Yeah, there’s a bug on this already.

Yeah, the filters are pretty slow. Keep in mind you can set yourself up a custom bookmark that has the filters already in place to save time, like this link, which pre-configures your dashboard to look only at English pages in the Web documentation that were changed in the past week:

So, the JavaScript documentation uses the syntax it does to satisfy the hard-core JavaScript folks, mostly. Including “prototype” in the JavaScript reference pages is actually a little controversial, as it confuses a lot of people who don’t really know much about the prototype basis of JavaScript, and don’t really care either. :slight_smile:

All APIs, on the other hand, are meant to be documented using the InterfaceName.methodName() or InterfaceName.propertyName syntax for their page titles. There are mistakes here and there and they need to be fixed; we try to do it as we spot them.

We also have some older pages which use different structures entirely, and those need to be updated once we finalize the current design rules (we’re very close now).

Float32Array was originally documented as a Web API, since it was introduced as part of WebGL before migrating into the core of JavaScript. That’s why there’s inconsistency there and on the other binary types documents. They should probably be updated as well.

Yeah, there are some inconsistencies and errors here and there. One way we’re trying to get that cleared up is by introducing the MDN content linter extension for Firefox. I would like to see us integrate a tool like it directly into the editor eventually.

(FWIW, headings shouldn’t have a title attribute) :slight_smile:

We tinker with doing things like this at times. I think you could totally write one but it would need to go through some testing, such as by running it on a local clone of MDN (which is thankfully totally possible!).

This was a conscious decision made long ago. We’re a site that documents the web. Not using HTML to document the web is not exactly a strong sign of support. Plus back when we made the decision, MediaWiki did not work well for us, as it broke certain types of code sample boxes and the like.

I personally agree with you on this. I get that there are benefits to having the macros/templates on GitHub (tests and the like to help avoid problems being introduced) but the down side is I think much greater. I have macro changes that I need in order to complete my work that have been languishing for weeks or months in some cases because nobody wants to review intricate macro changes and they don’t want to push them to production without a thorough review because of the risks of breaking something when changing a widely used macro. Yeah, there’s a risk there, but killing entire projects because nobody can invest the time in the review sort of breaks the entire system, I think.

I have at least four or five projects that were deliverables of mine that have been stalled for substantial amounts of time due to not being able to get macro changes into production.

I also agree that the number of steps involved in making even small changes to things like browser compatibility data are tedious to say the least. The system we have for storing the data in JSON and such is actually brilliant and I think is going to do great things for us, but the workflow as it stands is horrible.

I’d love forever the person who creates a really nice visual editor for our JSON data stores, complete with schema support to produce a custom UI and to validate the data before submitting a PR for me.



I see, thanks for the replies!

Setting the preceding period does the trick, that’s why the revisions wouldn’t load before, thanks.

Yeah, I understand why X.prototype.y is confusing. But what about using the hash symbol (X#y)? I’ve seen that notation used a lot, even in JavaScript contexts.

The current solution is not ideal for classes that have both static methods and class member methods because you don’t know what is what, especially when they are mixed together in the sidebar. In the main API page, you can at least put them under different sections.

Thanks, I’ll give that extension a try.
And I meant name="" and id="", d’oh.

(Eric Shepherd) #5

I’d like to say that my post above was maybe a little harsher than was intended. To be clear, I agree that there are logical reasons why we do things the way we do, and I did not intend to imply that anyone is falling down on the job or something. Indeed, the reason why my stuff is backlogged is partially my own fault, for not making a bigger deal out of these things being blockers on my work.

So… I’m sorry for the tone of that post, and as always, I appreciate the hard work of everyone on the MDN team. The reason there are things that don’t get done immediately is because of how incredibly hard everyone is working, not because of some sort of failing. :slight_smile:


(Eric Shepherd) #6

Yeah, I’m not sure what if any solution we’ve come up with for statics, but we need to do more, I think. You’re right on that.