Incorrect titles for method/property articles

MDN
21

Thanks, Janet. Yes, I made the change to consistently use “.prototype.” throughout the ECMAScript docs in 2013. I wanted this to be correct and closer to how the (at that point newish) ES6 spec named these things. I think it is important to clearly document static vs prototype built-in members. In 2013 I also discussed this with a few members of the MDN team, but we couldn’t agree on doing this throughout all Web API docs, so I just went with doing this for JS. I’m sorry if this created a somewhat inconsistent mess. Result of strong opinions colliding :slight_smile:

Now, 5 years later, I think we should revisit this, possible do some user research and agree to consistent titles based on user needs (web developers) rather being so opinion based.

I like “Array#push” as it is shorter than “Array.prototype.push”, but then you have to know what “#” stands for (and yes, private fields use “#” so this is a no-go now, I think). I guess now many also probably don’t know what “.prototype.” actually means. So, I maybe “Array: push() method” would work, and in the first summary sentence would have consistent wording that this is a prototype method. Worth doing research on.

Thanks Chris for going into this. This one isn’t easy.

Jean-Yves is also right, need to double check how this is used in macros. domxref and co come to mind, but also sidebars which list “properties” and “methods”. I think in JS docs you can easily differentiate statics vs prototype members in the sidebar (look at Array). I think for me it is even more import how it looks like in the sidebar than how it looks like in the page title or the h1. Right now this is coupled, but we could implement this differently so that the sidebar does not show page titles but something else.

So, I also added .prototype. because I like the sidebar like it is with the current titles:

Methods

  1. Array.from()
  2. Array.isArray()
  3. Array.of()
  4. Array.prototype.concat()
  5. Array.prototype.copyWithin()

If we’re changing the titles now, it would look like this:

Methods

  1. Array: static from() method
  2. Array: static isArray() method
  3. Array: static of() method
  4. Array: concat() method
  5. Array: copyWithin() method

So, doesn’t this look cluttered? Maybe sidebars should be thought through differently and be decoupled from the page title? Worth user testing as well in my opinion.

Florian