Incorrect titles for method/property articles

[sheppy (Eric Shepherd)]

I don’t understand your point about “when you’re in the moment writing code, 99% of the time this is how it looks”. That doesn’t ring true to me. When I’m in the moment writing code, it looks like self.close() , not SharedWorkerGlobalScope.close() . Or localStorage.getItem() , not Storage.getItem() . I don’t see how you could claim otherwise—the code you claim that it looks like, will in fact throw runtime exceptions

Well, I meant of course that you write it as myWhatever.close(), not myWhatever.prototype.close().

I also would strongly object to using the term “interface”. That is a Web IDL-ism only relevant to spec writers and browser developers, and one we’re considering fixing in Web IDL since it’s so misleading (it’s derived from Java). “Class” is the correct concept.

Well, when we started writing this stuff, JavaScript did not have classes, and did not until very recently. “Objects” would have been inaccurate since we’re dealing with something more akin to types, so we decided long ago to use “interfaces;” it’s still technically accurate although I agree that we might want to revisit it – although as far as I’m aware these are still not implemented as actual JavaScript classes. Are they?

I would also say that saying InterfaceName.methodName() doesn’t imply a static method unless you think it does. to me, if the word “static” isn’t there, it’s not a static method.

All of this said, I agree we need to consider making changes. JavaScript has evolved a lot since we first decided how this stuff should be documented. There were no statics (or if there were, they sure weren’t being used). I never encountered a static in documentation work on MDN until about a year ago – and I’ve been doing this since 2006, including a couple of years as the sole staff writer pounding out vast amounts of content.

I would personally prefer to use the same format we currently do but with added information afterward, such as “SharedWorkerOrGlobalScope.someImaginaryStaticMethod() static method”, as the page title.

You talk about the fundamental nature of prototypes in JavaScript, and while I agree that that’s true, I’ll also point out that I’ve been pretty successful working with JavaScript, including some pretty substantial projects, without ever really paying any attention to the topic of prototypes at all. I still don’t really fully get what they are and how they work, since I’ve never really needed to know in order to get my work done. So I find it hard to believe that the everyday JavaScript programmer desperately needs to know this.

[domenic (Domenic Denicola)]

Well, I meant of course that you write it as myWhatever.close(), not myWhatever.prototype.close().

Sure, if you titled the article mySharedWorkerGlobalScope.close(), that would be more accurate :).

Well, when we started writing this stuff, JavaScript did not have classes, and did not until very recently.

Not really true. It had classes, just not the class keyword.

it’s still technically accurate

It’s not; there is no such thing as an interface in JavaScript.

although as far as I’m aware these are still not implemented as actual JavaScript classes. Are they?

They are, and always have been.

I would also say that saying InterfaceName.methodName() doesn’t imply a static method unless you think it does.

It definitely does. For example of common statics, see e.g. Array.of(), Node.ELEMENT_NODE, or URL.createObjectURL(). You say ClassName.methodName() in those cases, and there it means what it says.

You talk about the fundamental nature of prototypes in JavaScript

I don’t intend to talk about the fundamental nature of prototypes at all. Prototypes are the least important thing here. All I’m saying that I’m not willing to link from the HTML spec’s specification of SharedWorkerGlobalScope to a set of docs which says that a static SharedWorkerGlobalScope.close() method exists, when such a method does not in fact exist and trying to use it will give errors.

[sideshowbarker (Michael[tm] Smith)]

Maybe worth considering: change to adopting a convention of using a shorthand of the form Array#push for these cases.

See https://mathiasbynens.be/notes/javascript-prototype-notation

When writing (in text, not in JavaScript) about properties on specific prototypes, you may use the JavaScript notation, foo.prototype.bar . However, this shorter (non-JavaScript) notation is often used instead: foo#bar . Basically, the hash ( # ) stands for .prototype.

Advantages:

• Array#push is shorter as a title than writing out Array.prototype.push. (Especially in cases like what we’re working on for the HTML spec annotations — where the MDN titles go into annotations in a 144px-wide margin — shorter is better.)
• Array#push isn’t JavaScript syntax, so it can’t be misunderstood as being something that MDN readers should actually use in their JavaScript code. Instead it’s unambiguously just a documentation convention. (I’ll concede it may be confusing initially to readers when they first see it used in MDN, but I think readers would quickly get around any initial confusion about it.)

[jswisher]

Some variant of this debate has recurred over at least 10 years.

Script authors don’t – and don’t need to – understand the prototype model, in the large, and virtually everyone who goes to the String page wants to know what they can do with Strings, not what they can do with the String constructor.
– Mike Shaver, January 18, 2008

Generally, the decision has been made in favor of usability/findability over technical accuracy. However, the JS language reference pages do use “.prototype”. See String.prototype.charAt() and anything linked from the JS Reference sidebar.

@fscholz undoubtedly has an opinion supporting the choice made in the JS reference; he’s currently out at a conference.

[sheppy (Eric Shepherd)]

I’ve actually argued repeatedly that we should restore the String pages to being just String.charAt() and so forth, because I agree with Shaver’s argument from 10 years ago (I actually literally remember that post and that conversation, because it was a big one at the time).

[sheppy (Eric Shepherd)]

We could look into some alternative title formats. After all, part of the SEO project is going to want to look into adding more to these titles anyway.

For instance, we could try titles like one of the below:

• SharedWorkerOrGlobalScope: close() method
• close() method (SharedWorkerOrGlobalScope)
• SharedWorkerOrGlobalScope close() method: Terminate a shared worker’s scope
• The SharedWorkerOrGlobalScope class’s close() method
• close() method (SharedWorkerOrGlobalScope class member) [or something worded with prototype if you insist ]

There are plenty of possible permutations; if we can find one we like, it could solve multiple problems with one shot.

[jswisher]

A certain popular site with high search rankings, which shall remain nameless, uses the title format “JavaScript String charAt() method”. Your third suggestion is similar but more detailed. Without the dot, there’s no direct implication that the method is a member of the class

[chrisdavidmills]

I have written all this information up into a plan:

Options for fixing titling of WebAPI reference pages

I’m intending to do some research and get some other opinions on what the best solution is. Feel free to comment.

[sideshowbarker (Michael[tm] Smith)]

Maybe worth considering: change to adopting a convention of using a shorthand of the form Array#push for these cases

In a comment at https://docs.google.com/document/d/19ZJbG3tp7CBygsFCj0BeY9CPWCcvnv75GZeTKhGzSlQ/edit#, @domenic points out:

as the JavaScript private fields and methods proposal advances, Interface.#member will become valid syntax (note the .). Differing from valid syntax by just a . is probably pretty confusing.

So given that, I agree SharedWorkerGlobalScope#close() wouldn’t be ideal.

But I think what would work well is SharedWorkerOrGlobalScope: close() method (one of the possibilities in @sheppy’s list of alternatives below, and also in the Options for fixing titling of WebAPI reference pages proposal.

In the context like the annotations for the HTML spec margin, where space is limited, the build for the annotations could just drop the method part from the title that’s shown in the hypertext of the link to the MDN article… But in the context of the actual title of the MDN article itself, it seems like it would be better to include method in the title.

[sideshowbarker (Michael[tm] Smith)]

SharedWorkerOrGlobalScope: close() method

I like this option. It’s shorter but still clear. And as I noted in an earlier comment, in contexts where an even-shorter reference to the article would be useful, the method part could be elided from the reference.

[chrisdavidmills]

So, an update. It looks like the most popular title suggestion is

InterfaceName: methodOrPropertyName (static) property/method

Examples:

• SharedWorkerOrGlobalScope: close() method
• URL: createObjectURL() static method
• Window: location property
• Notification: permission static property

I really like this too.

We also seem to like the “Other considerations” list:

• On interface landing pages, make sure static properties and methods are listed separately in “Static properties”/“Static methods” sections. The prototype properties/methods can just be listed in “Properties”/“Methods” sections.
• Update static property/method pages to include the word “static” clearly in the summary, e.g. “The Permission read-only static property of the Notification interface…” and “The createObjectURL() static method of the URL interface…”.
• If a situation arises where instance and static members collide (i.e. are called the same thing), add a disambiguation suffix to each slug, e.g. /x_prototype and /x_static, and a disambiguation page at /x.
• This should all be done for the JS built-in reference pages too. Let’s make everything consistent.

Future work:

• Investigate changing all instances of “interface” on MDN to “class” — “interface” is a historic WebIDL thing, but it conceptually wrong, and we seem to be moving towards “class”. The naming of ES2015 classes would support this too. This would need to be done carefully, and would take a bit of effort to make sure it is done across the whole site.

Before we do any of this, I am intending to do some further research and user testing.

[teoli (Jean-Yves Perrier)]

We have to be sure that macros like domxref and sidebars will continue to work after sny changement in slugs or titles.

I do think they will need to be updated, which will put constraints on the transition.

[chrisdavidmills]

Yup, there will definitely be some work needed here.

[sideshowbarker (Michael[tm] Smith)]

I can put significant time into helping with all the work needed.

It’s enlightened self-interest for me, because there are on the order of 350 MDN articles for methods and properties defined in the HTML spec that potentially need to be changed — and the HTML editors would really prefer to see those changed before landing my patch that adds annotations to the HTML spec for all those MDN articles.

[fscholz]

@fscholz undoubtedly has an opinion supporting the choice made in the JS reference; he’s currently out at a conference.

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

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

[chrisdavidmills]

So, doesn’t this look cluttered? Maybe sidebars should be thought through differently and be decoupled from the page title?

Yup, agreed. But I believe it was @sideshowbarker somewhere above suggested the idea of excluding the “method” and “property” words in sidebars, so we’d end up with something more like

1. Array: from() [STATIC]
2. Array: isArray() [STATIC]
3. Array: of() [STATIC]
4. Array: concat()
5. Array: copyWithin()

Think of [STATIC] as being like one of those little badges we use, like for READONLY, or whatever. I think this’d look best.

[domenic (Domenic Denicola)]

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 the idea of using user research. I have a strong suspicion that despite the views of a few folks in this thread, modern web developers actually do know and care what .prototype. means. But I can see I wouldn’t make progress against the folks here without data backing up that intuition.

[atopal (Kadir Topal)]

Happy to do more research on this, but if memory serves well, almost nobody among the users we have interviewed (more than 20 IIRC) was able to make sense of it. We could go back and re-evaluate those interviews.

[connorshea]

For what it’s worth, I didn’t (and still kind of don’t) understand the importance of .prototype.

I like the idea of resolving this with user research

[sheppy (Eric Shepherd)]

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.

This is a good point. We will have to handle this. But it should not be difficult to update macros around it. When generating the sidebar we can easily enough pull out from the title the information we actually need in the sidebar and just use that. Simple logic lets us remove everything up to and including the ": " at the beginning, excise the last word to decide which section of the sidebar to put the item in (methods, properties, etc). If the first word remaining is “static”, put it in the “static s” list, otherwise the regular list for that type of item.